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Preface 


The Macintosh Communications Toolbox Reference provides definitive 
information for application software developers, communications tools 
developers, and hardware developers who want to use services provided by 
the Macintosh® Communications Toolbox. For application software 
developers, this document describes and shows how to use the four 
Communications Toolbox managers and utilities that make it easier to write 
communications software for the Apple® Macintosh computer. For 
communications tools developers, this document shows how to develop 
communications tools that can be used by the Communications Toolbox 
managers. And for hardware developers, this document shows what 
protocols to follow to register hardware—like internal modems or serial 
cards—^with the Communications Toolbox Communications Resource 
Manager. 

About this document 

Chapter 1 contains an overview of the Communications Toolbox. Chapter 2 
presents a sample application that uses the Communications Toolbox. The next 
five chapters discuss the Communications Toolbox managers and utilities, 
describing the routines and data structures that an application uses. Each of 
these chapters contains a table that lists the routines in that chapter in the 
order in which they are described. Chapters 3 to 11 conclude with “Quick 
References” that summarize the contents of the chapter. Chapters 8 through 11 
show how to create a tool to add to the Communications Toolbox. While tool 
developers will be interested in reading these chapters, application developers 
may have little need to read them. Appendix A contains guidelines that 
communications tool developers should read to ensure that the tools they 
create are fully compatible with the Communications Toolbox. Appendix B 
provides sample code solutions to common programming problems. 



The Macintosh Communications Toolbox Reference is written for experienced 
programmers. Readers should know how to program the Macintosh and have 
some familiarity with communications or networking applications. To use 
each manager requires specific programming knowledge; suggestions on 
where to find more information are included at the beginning of each chapter. 
In addition, the next section lists resources for reference information about 
the technical concepts used in this document. 

For more information 

Refer to the following books in the Apple Technical Library and Apple 
Communications Library, published by Addison-Wesley, for additional 
information about the subjects covered in this manual: 

■ Designing Cards and Drivers for the Macintosh Family 

■ Human Interface Guidelines: The Apple Desktop Interface 

■ Inside Macintosh (Volumes I-V, X-ReO 

■ Programmer’s Introduction to the Macintosh Family 

■ Technical Introduction to the Macintosh Family 

■ AppleTalk Network System Overview 

■ Inside AppleTalk 

You may also refer to the following documents from APDA™: 

■ Software Development for International Markets: A Technical Reference 

■ Macintosh Technical Notes 

APDA provides a wide range of development products and documentation, 
from Apple and other suppliers, for programmers and developers who work 
on Apple equipment. For information about APDA, contact 

APDA 

Apple Computer, Inc. 

20525 Mariani Avenue, M/S 33-G 
Cupertino, CA 95014 

Telephone: 800-282-APDA (800-282-2732) 

Fax:408-562-3971 
Telex: 171-576 
AppleLink®: APDA 
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If you plan to develop Apple-compatible hardware or software products for 
sale through retail channels, you can get valuable support from Apple 
Developer Programs. Write to 

Apple Developer Programs 
Apple Computer, Inc. 

20525 Mariani Avenue, M/S 51-W 
Cupertino, CA 95014 

Conventions used in this document 

The following notations are used in this document to draw attention to 
particular items of information: 

♦ Note: a note that may be interesting or useful 

♦ Assembly note: a note of interest to assembly-language 

programmers only 

A Important a note that is particularly important 

A Warning a point that you need to be cautious about 

Words that appear in the glossary are presented in bold typeface when first 
introduced in the text. 

Names of routines (procedures or functions), constants, and code fragments 
appear in a special typeface, as in the following example: 

PROCEDURE GetDown(andBoogie : ONEMORETIME); 
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Communications Toolbox 



















































































THIS CHAPTER gives you an overview of the Macintosh® 
Communications Toolbox. It tells you about the managers and utilities that 
are part of the Communications Toolbox, and then discusses a fundamental 
concept, the difference between routines and tools. The last part of the 
chapter provides system hardware and software requirements, and shows 
how to install Communications Toolbox tools. 
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Communications Toolbox contents 

The Communiations Toolbox consists of four managers and a set of utilities. These managers and 
utilities are an extension to the Macintosh Toolbox and provide basic networking and 
communications services. Just as the Macintosh Toolbox makes it easier for you to develop stand¬ 
alone Macintosh applications, the Q)mmunications Toolbox helps you add networking and 
communiations functions to applications. 

Each of the managers in the Communiations Toolbox handles a different aspect of 
networking and communications; connection management, terminal emulation management, 
file transfer management, and communiations resource management. The managers provide 
routines that your appliation an call to indirectly interact with the operating system. Figure 1-1 
shows how the Communications Toolbox fits between your appliation and the operating system. 


Figure 1-1 Where the Macintosh Communiations Toolbox fits in 
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Although the managers in the Communications Toolbox handle distinctly different aspects of 
networking and communications, your application might need to call routines from more than one 
of the managers to implement a feature. For instance, in order to perform terminal emulation, in 
writing your program you might make use of Connection Mantlet routines to maintain the data 
connection, and Terminal Manager routines to handle the specifics of the terminal emulation. 

However, your application does not have to use Communications Toolbox routines to perform 
all of its networking and communications tasks; for example, your application can maintain the 
data connection itself and use only the Terminal Manager to perform a terminal emulation. Keep in 
mind, though, that using Communications Toolbox routines ensures greater compatibility for your 
application with new tools as they become available. 


Routines and tools: what’s the difference? 

There are two interfaces (besides the user interface) to consider when programming with the 
Communications Toolbox: the interface between the application and the Communications Toolbox, 
and the one between the Communications Toolbox and the Macintosh Operating System. 

The interface between an application and the Communications Toolbox is defined by the 
routines in each of the managers. By calling routines, an application can request basic networking 
and communications services. If you are writing applications (not tools), this is the interface with 
which you need to be most concerned; it is discussed in Chapters 3 through 7. 

The interface between the Communications Toolbox and the Macintosh Operating System is 
controlled by tools. Tools are units of code that implement the networking and communications 
services that your application requests. When an application calls a Communications Toolbox 
routine, it does so without concern for the underlying protocols. It is the job of the tool to 
implement basic networking and communications services according to a specific protocol. If you 
are writing tools (not applications), this is the interface with which you need to be most concerned; 
it is discussed in Chapters 8 through 11. Tools writers need to read at least two of these chapters: 
Chapter 8, which discusses concepts common to all typ)es of tools, and one of the other chapters 
that deals with a specific type of tool. 

Figure 1-2 shows the interaction between an application and one of the Communications Toolbox 
managers, in this case the Connection Manager. Notice that the application interacts with the 
Connection Manager, which in turn interacts with the connection tool The connection tool, in 
turn, communicates with a driver and passes back to the application (through the manager) any 
relevant information. (Chapter 3 contains a complete discussion of the Connection Manager.) 
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■ Figure 1-2 How Macintosh Communications Toolbox managers interact with 
applications and tools 



System requirements and installation 

The Communications Toolbox can be run on all Macintosh computers that have at least 1 megabyte of random- 
access memory, Macintosh Plus (128K) ROM or later, and system software 6.0.4 or a later version. Minimum disk- 
space requirements are two floppy disk drives, a single Apple® SuperDrive™, or a hard disk (which is 
recommended). 

♦ Note; On a 1-megabyte Macintosh running MultiFinder™, you may be able to run only a 
single application with the Finder™ coresident. You may also be unable to run HyperCard® 
under MultiFinder on a 1-megabyte Macintosh with the Communications Toolbox installed. 


You can install additional tools into the Communications Toolbox by dragging the icon for each tool into the 
folder named Communications Folder, which is inside the System Folder. Your application can access tools 
immediately after you have installed them (you don’t have to restart). 
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Chapter 2 Programming with the Macintosh 
Communications Toolbox 





































































THIS CHAPTER provides an example of how applications can use the 
Communications Toolbox to implement communications services. The example 
focuses on use of the Communications Toolbox, rather than on Macintosh 
programming in general. 

Thus, the sample code is not a complete program. It contains the parts of a 
program that handle communications functions; the rest of the program has 
been replaced with comments. This sample shows you where in an application 
to put the hooks to which you can attach Communications Toolbox routines. 

The sample application, if it were a real, working program, would allow you to 
perform functions that span the three major Communications Toolbox 
managers: the Connection Manager, the Terminal Manager, and the FUe 
Transfer Manner. Specifically, the sample source code shows you how to 

■ open and close a connection 

■ send and receive files 

■ configure connections, terminal emulations, and file transfers 

■ clear the screen 

■ reset the terminal 
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The sample code is split into three sections to make it easier to understand. The first section shows 
how your application can deal with events that result from menu selections; the sample application 
contains routines that handle basic communications services, like opening a connection and sending 
a file. The second section shows how your application can deal with events like scrolling and mouse 
clicks. The last section shows the sample application’s main code loop. You might find it helpful to 
read some of the chapters that discuss the managers before reading through the code. 

Assume the following globals 

VAR 


gTerm 

: TermHandle; 

{ tool records } 


gFT 

: FTHandle; 



gConn 

: ConnHandle; 



gBuffer 

: Ptr; 

{ My data buffer 

} 

gCache 

: Handle; 

{ 1-line cache } 


done 

: BOOLEAN; 

{ Main Event Loop 

Flag } 

gStartFT 

: BOOLEAN; 

{ Flag to start a 

transfer } 

gWasFT 

: BOOLEAN; 

{ Flag set during 

a transfer } 
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Menu events 


Handling menu choices 

PROCEDURE DoCommancKmResult : LONGINT); 

VAR 

theltem : INTEGER; { menu info } 

theMenu : INTEGER; 

BEGIN 

theltem := LoWord(mResult) ; { which item } 

theMenu := HiWord(mResult); { which menu } 

{ First see if the menu belonged to a tool } 

{ If the tool handles it, then leave } 

IF gTerm <> NIL THEN 

IF TMMenu(gTerm, theMenu, 

HiliteMenu(0); 

Exit(DoCommand); 

END; 

IF gConn <> NIL THEN 

IF CMMenu(gConn, theMenu, 

HiliteMenu(0); 

Exit(DoCommand); 

END; 

IF gFT <> NIL THEN 

IF FTMenu(gFT, theMenu, theltem) THEN BEGIN 
HiliteMenu(0); 

Exit(DoCommand); { FileTransfer tool handled it } 

END; 

{ Must be an application menu } 

(* 

Application menu handling goes here 
*) 

HiliteMenu(0); 

END; { DoCommand } 


theltem) THEN BEGIN 

{ Connection tool handled it } 


theltem) THEN BEGIN 

{ Terminal tool handled it } 
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Initiating a connection 


PROCEDURE Dolnitiate; 
VAR 


theErr : CMErr; 
sizes : BufferSizes; 
status : CMStatFlags; 


Problem Flag } 

Conn tool channel sizes } 
Conn tool states } 


BEGIN 


IF gConn <> NIL THEN BEGIN 

{ Get the state of the connection } 
theErr := CMStatus(gConn, sizes, status); 

{ If it*s not already open or opening, then open it } 

{ In this case, open it synchronous, no timeout } 

IF BAND(status, cmStatusOpen + cmStatusOpening) = 0 THEN 
theErr := CMOpen(gConn, FALSE, NIL, -1); 

IF theErr <> noErr THEN 

; { The tool will put up its own error alert } 

END; { Good handle } 

END; { Dolnitiate } 

Terminating the connection 

PROCEDURE DoKill; 

VAR 

theErr : CMErr; { Error codes } 

sizes : BufferSizes; { Tool Channel Sizes } 

status : CMStatFlags; { State of the connection } 


BEGIN 


IF gConn <> NIL THEN BEGIN 

{ Get the connection status } 

theErr := CMStatus(gConn, sizes, status); 

{ Close it only if it *s open or opening } 
{ In this case: synchronous, no timeout } 
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IF BAND(status, cmStatusOpen + cmStatusOpening) <> 0 THEN 
theErr := CMClose(gConn, FALSE, NIL, 0, TRUE); 

IF theErr <> noErr THEN 

; { The tool will put up its own error alert } 

END; { Good Connection } 

END; { DoKill } 


starting to send a file 

PROCEDURE DoSend; 

VAR 

theReply : SFReply; 
where : Point; 
nuitiTypes : INTEGER; 
typeList : SFTypeList; 
anyErr : FTErr; 

BEGIN 

IF gFT <> NIL THEN BEGIN { Good handle } 

{ Set location of the SFGetFile dialog } 

SetPt(where, 100, 100); 

{ If the FT tool can only send Text files, then } 

{ only display text files, else display all types } 

{ Check to see if Text Only flag is set} 

IF BAND (gFT'"^.attributes, ftTextOnly) <> 0 THEN BEGIN 
typeList[0] := *TEXT*; 

numTypes := 1; 

END 

ELSE 

numTypes := -1; 

SFGetFile(where, ’File to Send', NIL, 

numTypes, typeList, NIL, theReply); 

{ Did the user hit OK or Cancel } 

IF theReply.good THEN BEGIN 

{ Transfer the file TO the remote } 


{ File Info } 

{ upper-left corner of File dialog } 
{ File Types to display } 

{ Error handler } 
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anyErr := FTStart(gFT,ftTransmitting,theReply); 


IF (anyErr <> noErr) THEN 

; { Handle any errors here } 

END; { Good file } 

END; { Good FTHandle } 

END; { DoSend } 


starting to receive a file 

PROCEDURE DoReceive; 

VAR 

theReply : SFReply; { File Info } 

anyErr : OSErr; { Errors on Start } 


BEGIN 

IF gFT <> NIL THEN BEGIN 

{ Let the FT tool use its own default file info } 
theReply.vRefNum := 0; 
theReply.fName := 

{ Remove the search temporarily in case it } 

{ comes across during the transfer } 

(* 

Use CMRemoveSearch() to get rid of the file 
transfer auto-receive string search 
*) 

{ Start receiving the file } 

{ The rest gets transferred in the Idle loop } 

anyErr := FTStart(gFT,ftReceiving,theReply); 

IF (anyErr <> noErr) THEN 

; { Handle error conditions } 


END; { Good Handle } 
END; { DoReceive } 
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G)nfiguring a connection 

PROCEDURE DoConnectionConfig; 

VAR 

result : INTEGER; { Choose went OK? } 

where : Point; { upper-left corner of the choose dialog } 

tempStr : Str255; 


BEGIN 

{ Set the dialog box as close as possible to upper-left corner of screen } 
{ because the dialog box will grow down and/or to the right } 

SetPt(where, 10, 40); 

IF gConn <> NIL THEN BEGIN 

{ Put up the standard tool chooser } 
result := CMChoose(gConn, where, NIL); 

(* 

Handle the result here. 

If the tool has changed, need to re-add the file 
transfer auto-receive search to the new conn tool. 

*) 

END; { Good handle } 

END; { DoConnectionConfig } 


Configuring a terminal emulation 

PROCEDURE DoTerminalConfig; 

VAR 

result : INTEGER; { Choose went OK? } 

where : Point; { Upper-left corner of the choose dialog } 


BEGIN 

{ Set the dialog box as close as possible to top-left corner of screen } 
{ because the dialog box will grow down and/or to the right } 

SetPt(where, 10, 40); 

IF gTerm <> NIL THEN BEGIN 
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{ Put up the standard tool chooser } 
result := TMChoose(gTerm, where, NIL); 

(* 

“ Handle the result here 
*) 


END; { Good handle } 

END; { DoTerminalConfig } 

Configuring a file transfer 

PROCEDURE DoFileTransferConfig; 

VAR 

result : INTEGER; { User chose all right } 

where : Point; { upper-left corner of the dialog } 

tempString : STR255; { Search for FT sequence } 


BEGIN 

{ Set the dialog box as close as possible to top-left corner of screen } 
{ because the dialog box will grow down and/or to the right } 

SetPt(where, 10, 40); 

IF gFT <> NIL THEN BEGIN 

{ Put up the standard box } 

result := FTChoose(gFT, where, NIL); 

(* 

If the result = OKMajor or OKMinor, we may need to; 

remove the old file transfer auto-receive search (if any) 
add the new file transfer tool’s auto-receive string (if any). 

*) 

END; { Good Handle } 

END; { DoFileTransferConfig } 
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Making a new session document 

PROCEDURE MakeNew; 

VAR 

err 

theWindow 
theRect 
sizes 

t e rmEnvironment 
termID, 
ftID, 
connID 
toolName 
tempStr 

BEGIN 

{ Need a home } 
theWindow :== GetNewWindow(128, NIL, POINTER(—1) ) ; 

IF (theWindow = NIL) THEN BEGIN 
; { Handle Error } 

EXIT(MakeNew); 

END; 

SetPort(theWindow); 

{ Set up the termRect/viewRect for Term tool } 
theRect := theWindow'" .portRect; 

{ If we have scroll bars, we'll need to inset theRect } 
{ to account for their widths } 

gTerm := NIL; 
gConn := NIL; 
gFT := NIL; 
gBuffer := NIL; 
gCache := NIL; 

gStartFT := FALSE; 
gWasFT := FALSE; 


OSErr; 

WindowPtr; 

Rect; 

BufferSizes; 
TermEnvironRec; 


{ Errors from Environ call } 
{ Home for the terminal } 

{ TermRect for terminal } 

{ Connection tool buffers } 


INTEGER; 

Str255; 

Str255; 


{ proc IDs for the tools } 

{ who are they? } 

{ AutoReceive string for FT } 
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(- J 

{ New terminal tool } 

( - } 


(* 

Get the terminal tool’s proc ID by calling either 
CRMGetIndToolName() and/or TMGetProcID() 

*) 


{ New Terminal tool } 

gTerm := TMNew(theRect, theRect, tmSaveBeforeClear, termID, 
theWindow, @SendProc, @CacheProc, @BreakProc, 
NIL, @TermGetConnEnvirons, 0, 0); 

IF (gTerm = nil) THEN BEGIN 
{ Handle error } 

Exit( MakeNew ); 

END; 


I - j 

{ New connection tool } 

{ - j 


{ Set the desired sizes } 

sizes[cmDataIn] := 1024; { I only want data in this example } 

sizes[cmDataOut] := 1024; 

sizes[cmCntlln] := 0; { Ignore these channels } 

sizes[cmCntlOut] := 0; 
sizes[cmAttnIn] := 0; 
sizes[cmAttnOut] ;= 0; 

(* 

Get the connection tool’s proc ID by calling either 
CRMGetIndToolName() and/or CMGetProcID() 

*) 

{ Only want the data channel } 

gConn := CMNew(connID, cmData, sizes, 0, 0); 

IF (gConn = nil) THEN BEGIN 
{ Handle error } 

EXIT(MakeNew); 

END; 
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^ - } 

{ New file transfer tool } 

{ - } 


(* 

Get the file transfer tool's proc ID by calling either 
CRMGetIndToolName0 and/or FTGetProcID() 

*) 


{ ReadProc & WriteProc are nil to let } 

{ the tool handle the file i/o } 

gFT := FTNew(ftID, 0, @FTsendProc, @FTreceiveProc, NIL, NIL, 
@FTGetConnEnvirons,theWindow, 0, 0); 

IF (gFT = nil) THEN BEGIN 
{ Handle error } 

Exit(MakeNew); 

END; 

(* 

If the file transfer tool's auto-receive string isn't empty 
then add it with CMAddSearch(gFT,theString,flags,@AutoRecCallBack) 
*) 

gBuffer := NewPtr(1024) ; { the data buffer } 

IF (gBuffer = NIL) THEN 

; { Handle Errors } 

END; { MakeNew } 


{ Call Back Proc if a FT auto-receive string is found } 

PROCEDURE AutoRecCallback(gConn: ConnHandle; data: Ptr; refNum; LONGINT); 
BEGIN 

{ We can't call FTStartO or CMRemoveSearch () here as } 

{ this proc might be called from Interrupt level } 

gStartFT := TRUE; { Set the flag to call FTStart in Idle } 

END; { AutoRecCallBack } 
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Closing the session document 

PROCEDURE DoClose(theWindow: WindowPtr); 
BEGIN 


IF theWindow <> NIL THEN BEGIN 
IF gTerm <> NIL THEN 

TMDispose(gTerm) ; 

IF gConn <> NIL THEN 

CMDispose(gConn); 

IF gFT <> NIL THEN 

FTDispose(gFT); 

IF gBuffer <> NIL THEN 

DisposPtr(gBuffer); 

DisposeWindow(theWindow); 
END; { Good Window } 

END; { DoClose } 


{ Get rid of the tools } 

{ Tools should dispose of } 
{ their own windows } 


{ Get rid of my data space } 


{ Get rid of the window } 
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other events 


Activate events 


PROCEDURE DoActivate(theEvent : EventRecord); 
VAR 


theWindow : WindowPtr; 

processed : BOOLEAN; 


{ Activate or Deactivate } 


BEGIN 


theWindow := WindowPtr(theEvent.message) ; 


SetPort(theWindow) ; 


{ Focus on the target } 


{ Is this an activate or a deactivate } 

processed ;= BAND(theEvent.modifiers, activeFlag) <> 0; 

(* 

(Deactivate application stuff here 
*) 

{ Tools need to adjust their menus, text selection, etc } 

IF gTerm <> NIL THEN 

TMActivate(gTerm, processed); { Send message to the tool } 
IF gConn <> NIL THEN 

CMActivate(gConn, processed); { Send message to the tool } 
IF gFT <> NIL THEN 

FTActivate(gFT, processed); { Send message to the tool } 

END; { DoActivate } 

Resume events 

PROCEDURE DoResume(theEvent : EventRecord); 

CONST 

resumeFlag = 1; 


VAR 


theWindow : WindowPtr; 

isResume : BOOLEAN; 

savedPort : GrafPtr; 


Resume/Suspend Event } 


BEGIN 


GetPort(savedPort); 


Current Focus } 
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theWindow := FrontWindow; 


{ Get the target } 


{ Tools may work in background } 

IF theWindow <> NIL THEN BEGIN 
SetPort(theWindow); 

isResume := BAND(theEvent.message, resumeFlag) <> 0; 

IF gTerm <> NIL THEN 

TMResume(gTerm, isResume); 

IF gConn <> NIL THEN 

CMResume(gConn, isResume); 

IF gFT <> NIL THEN 

FTResume(gFT, isResume); 

SetPort(savedPort); 

END; { if good window } 

END; { DoResume } 


update events 

PROCEDURE DoUpdate(theEventlEventRecord); 

VAR 

theWindow : WindowPtr; 

savedPort : GrafPtr; 

savedClip : RgnHandle; 

BEGIN 

theWindow := WindowPtr(theEvent.message); 


IF theWindow <> NIL THEN BEGIN 



savedClip := NewRgn; 

{ Allocating 

for QD } 

GetPort(savedPort); 

{ Change the 

focus } 

SetPort(theWindow); 



GetClip(savedClip); 

{ Save the old area } 


ClipRect (theWindow'^ .portRect) ; { Just the window } 

BeginUpdate(theWindow); 

{ Clear the old data } 


{ The target to update } 

{ Temporarily saved } 

{ Clipping for the terminal } 
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EraseRect (theWindow'" .portRect) ; 


(* 

Update application stuff here 
*) 


{ Terminal tool will redraw } 


IF gTerm <> NIL THEN 


TMUpdate (gTerm, theWindow'^. visRgn) ; 


EndUpdate(theWindow); 


SetClip(savedClip); 
DisposeRgn(savedClip); 


Put it all back } 
Clean up } 


SetPort(savedPort); 

END; { Good Window } 

END; { DoUpdate } 

Keyboard events 

PROCEDURE DoKey(theEvent : EventRecord); 

VAR 

theKey : CHAR; { The character hit } 

processed : BOOLEAN; { Did the app handle it } 

result : LONGINT; { value MenuKeyO returns } 

BEGIN 

{ Get the character } 

theKey := CHAR(BAND(theEvent.message, charCodeMask)); 

processed := FALSE; { Haven't intercepted it } 

{ Was it a command equivalent } 

IF BAND(theEvent.modifiers, cmdKey) <> 0 THEN BEGIN 


result := MenuKey(theKey) ; 


{ Get the key equivalent } 
{ Valid menu key?? } 


IF theMenu <> 0 THEN BEGIN 


processed := TRUE; 
DoCommand(result); 


{ App will redirect } 

{ Calls the above routine } 


END; { Good Menu Equivalent } 


END; { Cmd-key down? } 
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{ If it wasn’t a valid menu command then pass the event to the terminal } 


IF (gTerm <> NIL) AND NOT processed THEN 
TMKey(gTerm, theEvent); 

END; { DoKey } 

Mouse events 

PROCEDURE DoClick(theEvent : EventRecord); 

VAR 

theWindow : WindowPtr; { The target } 

BEGIN 

{ Where was the click } 

thePart := FindWindow(theEvent.where, theWindow); 

CASE thePart OF 

inMenuBar: BEGIN 


END; 

{ Get the menu info } 

result := MenuSelect(theEvent.where); 

DoCommand(result); { call above routine } 

inGrow: 

BEGIN 

{ Resize the Window, scroll bars, etc. } 

END; 

{ Tell the terminal } 

TMResize (gTerm, theWindow'^ .portRect) ; 


inContent: 

IF gTerm <> NIL THEN BEGIN 
(* 



Call TMScrollO if the click was in a scroll bar 

*) 

END; 

TMClick(gTerm, theEvent); { For mouse selection } 

{ valid term rec } 

otherwise 


f 

{ Perform standard event action } 

END; { case } 


END; { DoClick } 
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Main program loop 


PROCEDURE MainLoop; 
VAR 


theEvent : EventRecord; 

theWindow : WindowPtr; 


{ World Happenstances } 
{ The desired target } 


BEGIN 


WHILE NOT done DO BEGIN 


Doldle; 


{ Call our idle proc once thru } 


IF WaitNextEvent(everyEvent,theEvent, 0, NIL) THEN BEGIN 

{ get the target window } 

CASE theEvent.what OF 


autoKey, keyDown: 

theWindow := FrontWindow; 
mouseDown: 


IF FindWindow(theEvent.where,theWindow)=0 THEN 


otherwise 

theWindow := WindowPtr(theEvent.message); 

END; { case } 

{ All windows created by a tool are supposed to } 

{ have their RefCons = LONGINT(theToolHandle) } 

(* 

Call the tool event proc if the window is a tool 
window. i.e. TMEvent() 

*) 

IF (theWindow <> NIL) THEN BEGIN 
SetPort(theWindow); 

CASE theEvent.what OF { App Window } 


autoKey, keyDown: 

{ May set done to true } 
DoKey(theEvent); 
mouseDown; 

{ May set done to true } 
DoClick(theEvent); 
updateEvt: 

DoUpdate(theEvent) ; 
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app4Evt: 

DoResume(theEvent); 
activateEvt: 

DoActivate(theEvent); 

END; { case } 

END; { Good Window } 

END; { WaitNextEvent } 

END; { while not done } 

END; { DoMainLoop } 
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THIS CHAPTER describes the Connection Manager, the Communications 
Toolbox manager that allows applications to establish and maintain 
connections. This chapter describes some of the fundamental concepts about 
the Connection Manager. Then it describes the connection record, which is 
the most important data structure to the Connection Manager. Next, this 
chapter presents a detailed functional description of each routine provided by 
the Connection Manager. At the end of the chapter, you’ll find a “Quick 
Reference” to routines, data structures, and routine selectors for programming 
in assembly language. 

In this chapter, the term your application refers to the application you are 
writing for the Macintosh, which will implement communications services 
for users. Be careful not to confuse the services your application provides 
with the services that tools provide. 

To use the Connection Manager, you need to be familiar with 

■ the Resource Manager (described in Inside Macintosh, Volumes I, IV, V) 

■ the Device Manager (described in Inside Macintosh, Volumes II, IV, V) 
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About the Connection Manager 

By using Connection Manager routines, your application can implement basic connection services without 
having to take into account underlying connection protocols. Connection tools, which are discussed in 
Chapter 9, are responsible for implementing connection services according to specific protocols. 

The Connection Manager provides a generic connection—a channel that carries data between your 
application and another computer process. The other process can be running on the same computer as your 
application or on any other computer. 

Here’s what happens inside the Connection Manager. An application makes a request of the Connection 
Manager when it needs a connection service, such as opening a connection. The Connection Manager then 
sends this request to one of the tools that it manages. The tool provides the service according to the 
specifics of the connection protocol that is implemented for the data connection. Once the tool has 
finished, it passes back to the application (through the manager) any relevant parameters and return codes. 

The data is sent along the connection in a byte stream (a reliable byte stream, if the connection protocol 
supports error correction), rather than on a transaction-by-transaction basis. Although the Connection 
Manager does not provide flow control, error correction, error detection, and data encapsulation, a tool or 
application can provide these services. 

Figure 3-1 shows the data flow into and out of the Connection Manager. 


■ Figure 3-1 Data flow into and out of the Connection Manager 
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The most important data structure maintained by the Connection Manager is the connection record, 
which stores all the specifics about a connection. For example, the connection record might show that 
a connection takes place over a direct serial port connection transmitting at 9,600 bits per second. 

One important aspect of the connection record is that it allows for protocol-independent 
routines. Protocol-independent routines allow applications to use Connection Manager services 
without regard for the underlying communications protocols. In other words, when an application 
wants to read data from a remote entity, it tells the Connection Manager to read, and the 
connection tool figures out exactly how to implement a read operation on a given connection. 

Another important feature of the connection record is that it lets you use multiple instances of 
the same tool. The same tool can be used by different processes at the same time, like in a 
MultiFinder environment, or by different threads in a given application. 

The connection record is described in greater detail later in this chapter. 

Besides providing basic connection routines, the Connection Manager includes routines that 
make it easy for your application to configure a connection tool, either by presenting the user with 
a dialog box or by interfacing directly with a scripting language. The Connection Manager also 
contains routines that make it easier for you to localize your applications in other languages. 

You can use the Connection Manager with other Communications Toolbox managers to create a 
communications application with file transfer and terminal emulation capabilities. Or, you can use 
the Connection Manager with some other data-transfer or terminal emulation service. You can also 
write your own connection tool for the Connection Manager to use. (This procedure is discussed in 
Chapters 8 and 9.) Regardless of which method you choose, your application should be able to handle 
different connection tools such that users can change tools and still be able to use your program. 


Connection channels: data, attention, and control 

when data is sent along a connection, there is a certain amount of overhead that sometimes 
accompanies it. This “extra” information could be a warning that the connection is about to go 
down or that the sending entity should slow its rate of transmitting data. Some connection 
protocols are designed in such a way that this sort of information can be sent simultaneously with 
the data stream on a channel. The Connection Manager supports up to three channels on each 
connection—data, attention, and control—that can be thought of as three separate lines of 
communication between each entity. The data channel, however, is for all protocols the primary 
channel for transmitting information between entities. The other two channels are used by only 
some connection protocols. 

When you design your application, keep in mind that some protocols support all three channels, 
whereas others support only one (the data channel). Your application should be able to handle different 
connection tools in a way that allows users to change tools and still be able to use your program. 
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The connection record 


The connection record contains information that describes a connection, as well as pointers to 
Connection Manager internal data structures. The Connection Manager uses this information to 
“translate” the protocol-independent routines used by an application into a service implemented 
according to a specified protocol. Most of the fields in the connection record are filled in when an 
application calls cMNew, described later in this chapter. 

Because the connection record describes how communications take place on a given 
connection, an application can communicate on more than one connection at the same time. All the 
application has to do is create a new connection record every time it initiates a new connection. 

A Important Your application, in order to be compatible with future releases of the 
Connection Manager, should not directly manipulate the fields of the 
connection record (with the exception of config and oidconfig). 

The Connection Manager provides routines that applications and tools can 
use to change connection record fields. These routines are discussed later in 
this chapter, a 


Connection record data structure 

TYPE 


ConnHandle = 

ConnPtr = 

ConnRecord = 

procID : 

'^ConnPtr; 

'^ConnRecord; 

RECORD 

INTEGER; 

flags : 

errCode : 

CMRecFlags; 

CMErr; 

refCon : 

userData : 

LONGINT; 

LONGINT 

defProc : 

ProcPtr; 

config : 

oldConfig : 

Ptr; 

Ptr; 

reservedO : 

reservedl : 

reserved2 : 

LONGINT; 

LONGINT; 

LONGINT; 

cmPrivate : 

Ptr; 

bufferArray : 

bufSizes : 

CMBuf fers; 

CMBufferSizes; 
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mluField 


LONGINT; 


asyncCount 


CMBufferSizes; 


END; 


procID 

prociD is the connection tool ID. This value is dynamically assigned by the Connection Manager 
when your application calls cMGetProcio. 


flags 

flags is a bit field that indicates certain specifics about a connection when the connection record 
is first created. The bit masks for flags are as follows; 

TYPE 

CMRecFlags = LONGINT; 

CONST 


cmData 

= 

$00000001; 

cmCntl 

= 

$00000002; 

cmAttn 

= 

$00000004; 

cmDataClean 

= 

$00000100; 

cmCntlClean 

= 

$00000200; 

cmAttnClean 


$00000400; 

cmNoMenus 


$00010000; 

cmQuiet 


$00020000; 


Your application can turn on the CMNoMenus or cMQuiet bits when it calls cMNew 
(discussed later in this chapter). The connection tool will set the rest of these bits. 

If the tool sets the cmoata, cmcnti, or cmAttn bit, your application can use a data, 
control, or attention channel. If the tool sets the cmoataciean, cmcnticiean, or 
cmAttnciean bit, your application can use a reliable (error-free, in-order-delivery) data, control, or 
attention channel. 

The connection tool will not display any custom menus if your application sets the 
cmNoMenus bit. The connection tool will not display any status dialog boxes or error alerts if your 
application sets the cmQuiet bit. If your application turns the cmQuiet bit on, it is 
responsible for displaying status dialog boxes and error alerts that the tool would have displayed. 
Applications typically use these two bits to hide the connection tool from the user. 

errCode 

errcode Contains the last error encountered by the Connection Manager. Valid error codes are as 
follows: 
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TYPE 


CMErr 


OSErr; 


CONST 


cmGenericError 

cmNoErr 

cmRejected 

cmFailed 

cmTimeOut 

cmNotOpen 

cmNotClosed 

cmNoRequeStPending 

cmNotSupported 

cmNoTools 


- 1 ; 

0 ; 

1 ; 

2 ; 

3/ 

4; 

5/ 

6 ; 

7; 

8 ; 


refCon 

ref Con is a four-bytc field that your application can use. 

userData 

userData is a four-byte field that your application can use. 

defProc 

defProc is a procedure pointer to the main code resource of the connection tool that will 
implement the connection protocol. The connection tool’s main code resource is of type ' cdef •. 

config 

conf ig is a pointer to a data block that is private to the connection tool. It can contain 
information like data transfer rate or parity for direct asynchronous connections, phone numbers 
for modem connections, or an address for an AppleTalk® connection; the contents vary from tool 
to tool. 

Your application can store the contents of config to save the state of a connection in a 
document. The structure, size, and contents of the configuration record are set by the tool. Your 
application can determine the size of the configuration record by calling GetPtrsize, overwrite its 
contents using BiockMove, and validate the contents with CMVaiidate. 

Your application can use CMGetconfig and CMSetconfig to manipulate fields in this 
record. For details, see “Interfacing with a Scripting Language,” later in this chapter. 

You can find more information about config from a connection tool perspective in Chapter 8. 

oldConfig 

oidconfig is a pointer to a data block that is private to the connection tool and contains the 
most recently saved version of config. Your application is responsible for setting oidconfig 
when the user saves a session document. 


Chapter 3: Connection Manager 33 




reservedO, reservedl, and reserved2 

reservedo, reservedl, and reserved2 arc fields that are reserved for the Connection 
Manager. Your application must not use these fields. 

emPrivate 

emPrivate is a pointer to a data block that is private to the connection tool. Your application 
must not use this field. 

bufferArray 

jijuf fis a set of pointers to buffers for the data, control, and attention channels. These 
are the buffers that are used to read data to or write data from the entity. These buffers are 
allocated by the connection tool and are the exclusive property of the connection tool; your 
application should not use these buffers. The data type for bufferArray is CMBuffers and 
is defined under the description of buf sizes. 


bufSizes 

bufsizes contains the actual sizes of the buffers and it, too, should not be manipulated directly by an 
application. The data type for bufsizes is cMBuffersizes, and is defined as follows: 

TYPE 

CMBufFields=( 

cmDataIn, 

cmDataOut 

cmCntlln 

cmCntlOut 

cmAttnIn 

cmAttnOut 

cmRsrvIn 

cmRsrvOut); 

CMBuffers = ARRAY[CMBufFieIds] OF Ptr; 

CMBufferSizes — ARRAY[CMBufFields] OF LONGINT; 


mluField 

mluFieid is a pointer to a private data structure that the Connection Manager uses when 
searching the data stream. 

asyneCount 

asynecount is used by completion routines to determine how many bytes were actually 
transmitted or received on a particular channel. Completion routines are discussed in more detail 
later in this chapter. 
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Connection Manager routines 

The following sections describe the routines that tools and applications can use to access Connection 
Manager services. These routines are protocol independent; your application does not need to be 
familiar with the specifics of a particular communications protocol in order to use the connection. Your 
application can call three Connection Manager routines from interrupt level: cMRead, CMwrite, and 
CMStatus. The other routines can not be called from interrupt level. 

Below is a listing of the routines described in this section in the order in which they are presented. 


InitCM / 36 
CMGetProcID / 37 
CMNew / 38 
CMDefault / 40 
CMValidate / 40 
CMChoose / 41 
CMSetupPreFlight / 43 
CMSetupSetup / 44 
CMSetupFilter / 44 
CMSetupItem / 45 
CMSetupCleanup / 45 
CMSetupPostFlight / 46 
CMGetConfig / 47 
CMSetConfig / 47 
CMOpen / 48 
enclose / 49 
CMAbort / 49 
CMDispose / 50 
CMIdle / 50 
CMListen / 50 
CMStatus / 51 
CMAccept / 52 


CMIOKill / 52 
CMReset / 53 
CMBreak / 53 
CMGetConnEnvirons / 54 
CMRead / 56 
CMWrite / 58 
CMAddSearch / 59 
CMRemoveSearch / 6 O 
CMClearSearch / 6 O 
CMActivate / 6l 
CMResume / 6l 
CMenu / 61 
CMEvent / 62 
CMIntlToEnglish / 63 
CMEnglishToIntl / 63 
CMGetToolName / 64 
CMSetRefCon / 64 
CMGetRefCon / 64 
CMSetUserData / 65 
CMGetUserData / 65 
CMGetVersion / 65 
CMGetCMVersion / 65 
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Preparing to open a connection 

Before your application can open a connection, it must initialize the Connection Manager (by calling 
initcM), find out the procio of the tool it requires (by calling CMGetProcio), create a 
connection record (by calling cMNew), and then configure the connection tool (by restoring 
conf ig from a saved document; or by calling cMChoose, the connection tool custom 
configuration routines, or cMSetconfig). 


InitCM 

Initializing the Connection Manager 

initCM initializes the Connection Manager. Your application should call this routine only 
once, after calling the standard Macintosh Toolbox initialization routines. 

A Warning Your application must initialize the Conununications Resource 

Manager (by calling initCRM) and then the Communications Toolbox Utilities (by 
calling initcTBUtiiities), whether or not it uses any of their calls, before it 
initializes the Connection Manager, a 

Function InitCM : CMErr; 

Description mitcM returns an operating-system error code if appropriate. Valid values are: 


TYPE 

CMErr = OSErr; 

CONST 

cmGenericError = -1; 

cmNoErr = 0/ 

cmRejected = 1; 

cmFailed = 2/ 

cmTimeOut = 3; 

cmNotOpen = 4; 

cmNotClosed = 5; 

cmNoRequestPending = 6; 

cmNotSupported = 7; 

cmNoTools = 8/ 


Your application must check for the presence of the CommToolbox before calling this 
function. Sample code under “Determining Whether the Managers are Installed” in 
Appendix B shows you how your application can make this check. 
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CMGetProcID 


Getting current prociD information 

Your application should call CMCetProciD just before creating a new connection 



record, to find out the proem of a tool. 

Function 

CMGetProcID(name: Str255): INTEGER; 

Description 

name Specifies a connection tool. If there is a connection tool in the folder named 
Communications FoldermihthtsptaSxtdi name, its proem is returned. If name 
references a nonexistent connection tool, -1 is returned. 
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CMNew 


Creating a connection record 

Before your application can open a connection, it must create a connection record so the 
Connection Manager knows what type of connection to establish. cMNew creates a new 
connection record; fills in the fields that it can, based upon the parameters that were 
passed to it; and returns a handle to the new record in connHandie. CMNew 
automatically makes two calls to cMoe fault (which is described later in this chapter) 
to fill in conf ig and oidconf ig. The Connection Manager then loads the connection 
tool main code resource, moves it high in the current heap, and locks it. If an error occurs 
that prevents a new connection record from being created (for example, running out of 
memory), CMNew passes back nil in connHandie. 

Function CMNew(procID : INTEGER; flags : CMRecFlags; desiredSizes ; 

CMBufferSizes; refCon : LONGINT; userData : LONGINT) : 
ConnHandie; 

Description prooiD is dynamically assigned by the Connection Manager to tools at run time. 

Applications should not store procio values in settings files. Instead, they should store 
tool names, which can be converted to procio values with the cMGetProcio 
routine. Your application should use the ID that cMGetProciD returns for procio. 

flags is a bit field with the following masks: 

CONST 


cmData 

= 

$00000001; 

cmCntl 

= 

$00000002; 

cmAttn 

= 

$00000004; 

cmDataClean 


$00000100; 

cmCntlClean 

= 

$00000200; 

cmAttnClean 


$00000400; 

cmNoMenus 


$00010000; 

cmQuiet 

= 

$00020000; 


flags represents a request from your application for a level of connection service. 

If your application sets cmNoMenus, the connection tool will not display any custom 
menus. If your application sets cmQuiet, the connection tool will not display any 
windows. Applications typically use these bits to hide the connection tool from the user. 

The coimection tool sets the other bits, and returns in the flags field of the 
connection record the level of connection service that it grants your application. The 
flags field is discussed in “Connection Record Data Structure,” earlier in this chapter. 

Apple Computer has reserved the bits of flags not shown in this manual. Do not 
use them, or your code may not work in the future. 
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desiredsizes specifies buffer sizes that your application requests for its read, write, 
control read, control write, attention read, and attention write channels. Your application 
can specify the sizes that it wants when it calls CMNew, but the connection tool might 
not provide the requested sizes. To have the tool set the size of these buffers, your 
application should put zeros in the array. These buffers become the exclusive property of 
the connection tool and should not be manipulated by the application in any way. The 
actual buffer sizes are kept in the bufsizes field of the connection record. 

refcon and userData are fields that your application can use. 
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CMDefault 


Initializing the configuration record 

CMDefault fills the specified configuration record with the default configuration 


Procedure 

Specified by the connection tool. CMNew calls this procedure automatically when it fills 
in the config and oidconfig fields in a new connection record 

CMDefault(VAR theConfig: Ptr; procID: INTEGER; allocate: 

BOOLEAN); 

Description 

If allocate is TRUE, the tool allocates Space for theConfig in the current heap 

zone. 

CMValidate 



Validating the configuration record 

cMvaiidate performs an internal consistency check on the configuration and private 


Function 

data records of the connection record. CMNew and cMSetconf ig call this routine after 
they have created a new connection record, to make sure that the record contains values 
identical to those specified by the connection tool. 

CMValidate(hConn: ConnHandle): BOOLEAN; 

Description 

If the validation fails, the Connection Manager returns true and the tool fills the 
configuration record with default values by calling cMOefauit. 

Your application can call this routine after restoring a configuration, to verify 
that the connection record contains the correct information, in a manner similar to 
that shown next. 

BlockMove(saveConfig,hConn^*.config,GetPtrSize(hConn^^.config)); 
IF CMValidate(hConn) THEN BEGIN 
{ validate failed } 

END 

ELSE BEGIN 

{ validate succeeded } 

END 
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CMChoose 


Configuring a connection tool 

An application can configure a connection tool in one of three ways. The easiest and most 
straightforward way is by calling the CMChoose routine. This routine presents the user 
with a dialog box similar to the one shown in Figure 3-2. 


■ Figure 3-2 The standard tool-settings dialog box 


This area is 
filled in by the — 
connection tool. 



The second way an application can configure a connection tool is by presenting the user 
with a custom tool-settings dialog box. This method is much more difficult, and involves 
calling six routines. The routines are described in the next section, “Custom Configuration 
of a Connection Tool,” and “The Custom Tool-Settings Dialog Box” in Appendix B 
provides example code. 

The third way your application can configure a connection tool is by using the 
scripting language interface, described in “Interfacing With a Scripting Language,” 
later in this chapter. This method allows your application to bypass user interface 
elements. 

Function CMChoosetVAR hConn:ConnHandle; where: Point; IdieProc: 

ProcPtr): INTEGER; 

Description where is the point, specified in global coordinates, where the upper-left comer of the 

dialog box should appear. It is recommended that your application place the dialog box as 
close as possible to the upper-left comer of the screen, because the size of the dialog box 
varies from tool to tool. 
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idieProc is a procedure with no parameters that the Connection Manager will 
automatically call every time cMChoose calls the setup dialog box filter procedure. 
Pass NIL if your application has no idieProc. 

CMChoose returns one of the following values: 


CONST 

chooseDisaster = -2 
chooseFailed = -1 
chooseAborted = 0 
chooseOKMinor = 1 
chooseOKMajor = 2 
chooseCancel “ 3 


chooseDisaster means that the CMChoose operation failed, destroyed 
the connection record, and returned nil in the connection handle. 

ChooseFailed means that the cMChoose operation failed and the 
connection record was not changed. 

ChooseAborted means that the user started to change the connection while 
it was still open but changed their mind. When users try to change connection tools 
while the connection is still open, the Connection Manager prompts them with a 
dialog box that asks if they want to make the change. If the user clicks No in this 
dialog box, the CMChoose routine returns chooseAborted. 

ChooseOKMinor means that the user clicked OK in the dialog box but did not 
change the connection tool being used. 

ChooseOKMa jor means that the user selected OK in the dialog box and also 
changed the connection tool being used. The Connection Manager then destroys 
the old connection handle by calling CMDispose. The connection is closed down, 
all pending read and write operations are terminated, and a new connection handle is 
returned in hconn. 

chooseCancel means that the user clicked Cancel in the dialog box. 
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Custom configuration of a connection tool 

Your application creates a custom tool-settings dialog box and presents it to the user by using the six 
Connection Manger routines: CMSetupPreflight, CMSetupSetup, CMSetupFilter, CMSetupItem, 
CMSetupcieanup, and CMSetupPostflight. Using these routines is more involved than calling 
CMChoose, but they provide your application with much more flexibility. Refer to the code sample in “The 
Custom Tool-Settings Dialog Box” in Appendbc B to see how an application calls these routines. 

To build a list of available connection tools, use the routine CRMGetindTooiName, which is 
described in Chapter 6. 


CMSetupP re f1ight 

Setting up the custom tool-settings dialog box 

CMSetupPref light retums a handle to a dialog item list that your application appends 
to the custom tool-settings dialog box. The handle comes from the connection tool. (The 
calling application uses AppendoiTL, discussed in Chapter 7.) This handle is not a 
resource handle. Your application is responsible for disposing of the handle when done 
with it. 

The connection tool can use CMSetupPrefiight to allocate a block of private 
storage, and to store the pointer to that block in magicCookie. The magicCookie 
value should be passed to the other routines that are used to set up the custom tool- 
settings dialog box. 

Function CMSetupPreflight(procID: INTEGER; VAR magicCookie: LONGINT): 

Handle; 

Description prociD is the ID for the connection tool that is being configured. Your application 

should get this value by using the CMGetProcio routine, discussed earlier in this 
chapter. 

♦ Note: The ref con of the custom tool-settings dialog box should point to a data 
structure (shown next) in which the first two bytes are the tool procio and the next 
four bytes are magicCookie. useritem routines, for example, may require procio 
to obtain tool resources. 

TYPE 

chooseDLOGdata = RECORD 

prociD : INTEGER 

magicCookie : LONGINT 

END; 
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CMSetupSetup 


Setting up custom tool-settings dialog box items 

CMSetupSetup tells the connection tool to set up controls (like radio buttons or check 
boxes) in the dialog item list returned by cMSetupPref light. 


Procedure 

CMSetupSetup(procID: INTEGER; theConfig: Ptr; count: INTEGER; 
theDialog: DialogPtr; VAR magicCookie: LONGINT); 

Description 

prociD is the ID for the connection tool that is being configured. Your application 
should use the same value for procio as it passed to cMSetupPreflight. 

theConfig is a pointer to a configuration record for the tool being configured. 

count is the number of the first item in the dialog item list appended to the dialog box. 

theDialog is the dialog box in which configuration is taking place. 

magicCookie is a pointer to private storage for the connection tool. 


CMSetupFilter 


Filtering custom tool-settings dialog box events 

Your application calls CMSetupFiiter as a filter procedure before it calls the standard 


Function 

modal dialog box filter procedure for the custom tool-settings dialog box. This routine 
allows connection tools to filter events in the custom tool-settings dialog box. 

CMSetupFilter(prociD: INTEGER; theConfig: Ptr; count:INTEGER; 
theDialog: DialogPtr; VAR theEvent: EventRecord; VAR theltem: 
INTEGER; VAR magicCookie: LONGINT): BOOLEAN; 

Description 

prociD is the ID for the connection tool that is being configured. Your application 
should use the same value for prociD as it passed to CMSetupPref light. 

theConfig is a pointer to the configuration record for the tool being configured. 

count is the number of the first item in the dialog item list appended to the dialog box. 

theDialog is the dialog box performing the configuration. 

theEvent is the event record for which filtering is to take place. 

theltem can return the item clicked in the dialog box. 

magicCookie is a pointer to private storage for the connection tool. 

If the event passed in was handled, CMSetupFiiter returns true, false 
indicates that your application should perform standard dialog box filtering. 
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CMSetupItem 


Processing custom tool-settings dialog box events 

CMSetupItem processes events for controls in the custom tool-settings dialog box. 


Procedure 

CMSetupItem(procID: INTEGER; theConfig: Ptr; count: INTEGER; 
theDialog: DialogPtr; VAR theltem: INTEGER; VAR magicCookie: 
LONGINT); 

Description 

prociD is the ID for the connection tool being configured. Your application should use 
the same value for procio as it passed to CMSetupPreflight. 

theConfig is a pointer to the configuration record for the tool being configured. 

count is the number of the first item in the dialog item list appended to the dialog box. 

theDialog is the dialog box performing the configuration. 

theltem is the item clicked in the dialog box. This value can be modified and sent back. 

magicCookie is a pointer to private storage for the connection tool. 


CMSetupCleanup 


Performing clean-up operations 

CMSetupCleanup disposes of any storage allocated in cMSetupPref light and 


Procedure 

performs other clean-up operations. If your application needs to shorten a dialog box, it 
should do so after calling this routine. 

CMSetupCleanup(procID: INTEGER; theConfig: Ptr; count: INTEGER; 
theDialog: DialogPtr; VAR magicCookie: LONGINT); 

Description 

prociD is the ID for the connection tool that is being configured. Your application 
should use the same value for prociD as it passed to CMSetupPreflight. 

theConfig is a pointer to the configuration record for the tool being configured. 

count is the number of the first item in the dialog item list appended to the dialog box. 

theDialog is the dialog box performing the configuration. 

magicCookie is a pointer to private storage for the connection tool. 
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CMSetupPostflight 


Closing the tool file 

CMSetupPostf light closes the tool file if it is not being used by any sessions. 
Procedure CMSetupPostflight(procID:INTEGER) ; 

Description prociD is the ID for the connection tool that is being configured. Your application 

should use the same value for prociD as it passed to cMSetupPreflight. 
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Interfacing with a scripting language 

Your application does not have to rely on users making selections from dialog boxes in order to 
configure a connection tool. cMGetconf ig and cMSetconf ig provide the services that your 
application needs to interface with a scripting language. 

CMGetConfig 


Getting the configuration string 

CMGetConfig gets a configuration string from the connection tool. 


Function 

CMGetConfig(hConn: ConnHandle): Ptr; 

Description 

CMGetConfig retums a null-terminated, C-style string from the connection tool 
containing tokens that fully describe the configuration of the connection record. For an 
example, see the description of the next routine. If an an error occurs, CMGetConfig 
returns nil. 

It is the responsibility of your application to dispose of ptr. 

CMSetConfig 



Setting the configuration with a string 

CMSetconfig passes a configuration string to the connection tool. 


Function 

CMSetconfig(hConn: ConnHandle; thePtr: Ptr): INTEGER; 

Description 

CMSetconfig passes a null-terminated, C-style string (see the example string later in 
this section) to the connection tool for parsing. The string is pointed to by thePtr and 
must contain tokens that describe the configuration of the connection record. The string 
can be any length. 

CMSetconfig ignores items it does not recognize or find relevant; such an 
occurrence causes the connection tool to stop parsing the string and to return the 
character position where the error occurred. If the connection tool successfully 
parses the string, it retums cmnoErr. If the connection tool does not 
successfully parse the string, it returns one of the following values: a number less 
than -1 to indicate an osErr, -1 to indicate an unknown error, or a positive 
number to indicate the character position where parsing was stopped. 

Individual connection tools are responsible for the parsing operation. 

Sample 

A null-terminated, C-style configuration string 

Baud 9600 dataBits 8 Parity None StopBits 1 Port "Modem Port" 

Handshake None HoldConnection False RemindDisconnect False\0 
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opening, using, and closing the connection 

Once your application has performed the required tasks described in the previous sections, it can 
open and use a connection. 

CMOpen 


Opening a connection 



CMOpen attempts to open a connection, based on information contained in a connection 
record. 

Function 

CMOpen(hConn: ConnHandle; async: BOOLEAN; completor: ProcPtr; 

timeout: LONGINT): CMErr; 

Description 

hconn points to the connection record for the new connection. 

async Specifies whether or not the opening request is asynchronous. If your application 
makes an asynchronous request, cMOpen returns cmNoErr immediately. 

completor Specifies the completion routine to be called upon completion of an 
asynchronous open request. Completion routines are discussed in greater detail later in this 
chapter, in the section “Completion Routines.” 

timeout Specifies a time period, in ticks, within which CMOpen must be completed 
before the connection tool returns a cmTimeOut error. For no timeout, use -1. For a 
single attempt to open the connection, use 0. Some connection tools ignore this 
parameter. 

If no error occurs during the open attempt, cMOpen returns cmNoErr. CMOpen 
returns a negative number if an operating-system error occurred, or a positive number if a 
Connection Manager error occurred. 
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CMClose 


Closing a connection 

CMClose closes a connection that is already open or in the process of opening. 

Function CMClose(hConn: ConnHandle; async: BOOLEAN; completor: ProcPtr; 

timeout: LONGINT; now: BOOLEAN): CMErr; 

Description async specifies whether or not the close request is asynchronous. If your application 

requests an asynchronous close, CMciose returns noErr immediately. 

completor Specifies the completion routine to be called upon completion of an 
asychronous close request. Completion routines are discussed in greater detail later in this 
chapter, in the section “Completion Routines.” 

timeout specifies a time period, in ticks, within which the close operation must be 
completed before the connection tool returns a cmTimeOut error. For no timeout, 
use -1. For a single try to close the connection, use 0. Some connection tools ignore this 
parameter. 

When now is true, the connection tool closes the connection immediately. When now 
is FALSE, the connection tool waits until all pending input and output have completed 
before closing the connection. 


CMAbort 

Aborting a connection 

CMAbort tells the Connection Manager to stop trying to complete a pending 
asynchronous open request. Any open completion routines are executed. Your application 
can also call this routine to stop an outstanding CMListen. 

Function CMAbort(hConn: ConnHandle): CMErr; 

Description hConn specifies the connection this routine affects. 
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CMDispose 


Disposing of a connection record 


Procedure 

CMDispose disposcs of the connection record and all associated data structures. It is up 
to the connection tool to decide whether or not to wait for all pending read and write 
operations to complete before closing and disposing of the connection. 

CMDispose(hConn: ConnHandle); 

Description 

hconn Specifies the connection record disposed of by this routine. 

CMIdle 



Idle procedure 

Your application should all CMidie at least once every time it goes through its main 


Procedure 

event loop, so that the connection tool can perform idle-loop tasks. 

CMIdle(hConn: ConnHandle); 

Description 

hConn specifies the connection for which idle-loop tasks are to be performed. 

CMListen 



Listening for incoming connection requests 

cMListen “listens” for a connection request from another entity. Your appliation, 


Function 

after it calls CMListen , should call CMStatus (which is described later in this section) 
to see if a connection request has been received (by checking the 

cmStatusIncomingCallPresent bit). 

CMListen(hConn: ConnHandle; async: BOOLEAN; completor: ProcPtr; 
timeout: LONGINT): CMErr; 

Description 

async specifies whether or not the opening request is asynchronous. If your application 
makes an asynchronous request, CMListen returns cmNoErr immediately. If your 
application makes a synchronous request, CMListen stays in a “listen loop” until it 
receives the connection request. 

completor Specifies the completion routine that the Connection Manager calls after it 
is done listening for the connection request. Completion routines are called only after 
asynchronous calls to CMListen. “Completion Routines,” later in this chapter, discusses 
completion routines in more detail. 

timeout specifies a time period, in ticks, within which a connection request must 
be received before the connection tool returns a cmTimeOut error. For no timeout, 
use -1. For a single listen, use 0. Some connection tools ignore this parameter. 
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CMStatus 


Getting connection status information 


Function 


Description 


CMStatus returns a variety of useful status information about a connection. Your 
application can call this routine at interrupt level. 

CMStatus(hConn: ConnHandle; VAR sizes: CMBufferSizes; VAR 
flags: CMStatFlags): CMErr; 

sizes is variable of type CMBuffersizes that contains the number of characters to 
be read or written on the data, control, and attention channels. The indexes of the array 
are as follows: 

cmDataIn, cmDataOut, cmCntlln, cmCntlOut, cmAttnIn, cmAttnOut, 
cmRsrvin, cmRsrvOut. 


flags is a bit field with the following masks: 

CONST 

cmStatusOpening = 

cmStatusOpen = 

cmStatusClosing = 

cmStatusDataAvail = 

cmStatusCntlAvail = 

cmStatusAttnAvail = 

cmStatusDRPend =* 

cmStatusDWPend = 

cmStatusCRPend = 

cmStatusCWPend =* 

cmStatusARPend = 

cmStatusAWPend = 

cmStatusBreakPending - 

cmStatusListenPend = 

cmStatusIncomingCallPresent = 

TYPE 

CMStatFlags 


{tool is opening connection} 
$ 00000001 ; 

(connection is open} 

$ 00000002 ; 

(tool is closing connection} 
$00000004; 

(data present on data channel} 
$00000008; 

(data present on cntl channel} 
$ 00000010 ; 

(data present on attn channel} 
$ 00000020 ; 

(data read pending} 

$00000040; 

(data write pending} 

$00000080; 

(cntl read pending} 

$ 00000100 ; 

(cntl write pending} 

$ 00000200 ; 

(attn read pending} 

$00000400; 

(attn write pending} 

$00000800; 

(tool is brea)cing the connection} 
$ 00001000 ; 

(tool is "listening" for data} 
$ 00002000 ; 

(call waiting for tool to handle} 
$00004000; 


LONGINT; 
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CMAccept 


Accepting or rejecting a connection request 

CMAccept accepts or rejects an incoming connection request. 

Function CMAccept(hConn:ConnHandle; accept:BOOLEAN): CMErr; 

Description Typically, an application will perform some actions after a cMListen, the results of 

which determine whether or not to accept the request. CMAccept cannot be called 
from interrupt level. 


CMIOKill ___ 

Stopping an asynchronous input/output request 

CMIOKill terminates any pending input/output (I/O) requests on the specified channel. 

Function CMIOKill(hConn: ConnHandle; which: INTEGER): CMErr; 

Description which indiates the channel, and can take one of the following values: 

cmDataIn, cmDataOut, cmCntlln, cmCntlOut, cmAttnIn, cmAttnOut, 
cmRsrvIn, cmRsrvOut. 
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CMReset 


Resetting the connection 

CMReset causes the connection to be reset. The exact state to which the connection is 
reset depends upon the connection protocol being implemented. The connection tool 
clears all local read and write buffers. 


Procedure CMReset (hConn: ConnHandle) ; 


CMBreak 

Sending breaks 

CMBreak effects a break operation upon the connection. The exact effect of this 
operation depends upon the tool in use. 

Procedure CMBreak(hConn: ConnHandle; duration: LONGINT; async: BOOLEAN; 

completor: ProcPtr)/ 

Description duration specifies in ticks the length of the break. 

completor specifies the completion routine to be called upon completion of the break. 
Completion routines are called only after asychronous calls to CMBreak. “Completion 
Routines,” later in this chapter, discusses completion routines in more detail. 
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CMGet ConnEnvirons 


Getting the connection environment 

CMGetconnEnvirons provides a means for obtaining connection environment 
information. 


Function 


Description 


CMGetconnEnvirons (hConn : ConnHandle; VAR theEnvirons : 
ConnEnvironRec) : CMErr; 


CMGetconnEnvirons retums the connection environment record in theEnvirons 
for the connection specified by connHandie. The connection tool is responsible for 
filling in each field of ConnEnvironRec with either a value (if it has a valid value to 
supply) or 0. 

The structure for version 0 of the connection environment record is as follows; 


TYPE 

ConnEnvironRecPtr 
ConnEnvironRec 
version 

baudRate 

dataBits 

channels 

swFlowControl 

hwFlowControl 

flags 

END; 


^ConnEnvironRec; 

RECORD; 

INTEGER; 

{version of this data structure} 
LONGINT; 

(data transfer rate} 

INTEGER; 

{number of significant bits per byte} 
CMChannel; 

{supported channels} 

BOOLEAN; 

{if software flow control is in use} 
BOOLEAN; 

{if hardware flow control is in use} 
CMFlags; 


The version field takes on the following value: 

CONST 

curConnEnvRecVers = 0; 


The flags field of the ConnEnvironRec is a bit field with the following value: 
TYPE 

CMFlags = INTEGER; 

CONST 

cmFlagsEOM = $0001; 

Other bits of flags are reserved by Apple Computer 
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channels is a bit field with the following values: 

TYPE 


CMChannel 

= 

INTEGER; 

CONST 

cmData 

= 

$00000001; 

cmCntl 


$00000002; 

cmAttn 

* 

$00000004; 

cmDataClean 

=: 

$00000100; 

cmCntlClean 

= 

$00000200; 

cmAttnClean 

= 

$00000400; 


Other bits of channels are reserved by Apple Computer 
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Reading and writing data 

The Connection Manager provides routines that read from and write data to a buffer. Your 
appliation can also use the Connection Manager routine that reads data, CMRead, to search the 
incoming data stream for a specified pattern of bytes. Data stream searching is discussed later in 
this chapter in the section “cMAddSearch : Adding a Data Stream Search.” 

CMRead 


Reading data 

CMRead reads data into a block of memory. Your application can not queue multiple read 



requests for the same channel on the same connection. However, your application can 
have both a pending read and a pending write on the same channel at the same time. Your 
application can call this routine at interrupt level. 

♦ Note: Your application should not check for an open channel prior to reading data. The 
connection tool might be interpreting data locally and, therefore, not need an open 
connection. 

Function 

CMRead(hConn; ConnHandle; theBuffer: Ptr; VAR toRead: LONGINT; 
theChannel: CMChannel; async: BOOLEAN; completor: ProcPtr; 
timeout: LONGINT; VAR flags: CMFlags): CMErr; 

Description 

theBuffer specifies the buffer to which the connection tool should read data. 

toRead specifies the number of bytes to be read. If your application calls this routine 
synchronously, the connection tool returns the actual number of bytes it read in 
toRead. Your application can call cMstatus to see if an asychronous read is pending. 

If your application calls this routine asynchronously, the asynccount field of the 
connection record contains the actual number of bytes read when the connection tool 
calls the completion routine. 

thechanne 1 specifies the channel on which reading takes place. Acceptable values are as 
follows: 

CONST 

cmData = $00000001; 

cmCntl = $00000002; 

cmAttn = $00000004; 

async specifies whether or not the request is asynchronous. If an asynchronous request 
is made, cmNoErr is returned immediately. 
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compietor Specifies the completion routine to be called upon completion of an 
asynchronous read request. Completion routines are discussed in greater detail later in this 
chapter in the section “Completion Routines.” 

timeout specifies a time period, in ticks, within which the connection tool must 
complete the read operation. If it does not complete within the specified time, a timeout 
error occurs. For no timeout, use -1. If your application specifies 0, the connection tool 
reads as many bytes, up to toRead bytes, as it can in one read attempt. Some 
connection tools ignore this parameter. 

flags indicates whether or not your application received an end-of-message indicator. 

If your application calls this routine asynchronously, the connection tool returns the end 
of message indicator in the reservedo field of the connection record when the 
completion routine is called. 

CONST 

cmFlagsEOM = $0001; 
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CMWrite 


Writing data 


♦ 


Function 


Description 


CMWrite writes data from a block of memory. Your application can not queue multiple 
write requests for the same channel on the same connection. However, your application 
can have both a pending read and a pending write on the same channel at the same time. 
Your application can call this routine at interrupt level. 

Note: Your application should not check for an open channel prior to writing data. The 
connection tool might be interpreting data locally and, therefore, not need an open 
connection. 


CMWrite(hConn: ConnHandle; theBuffer: Ptr; VAR toWrite: 

LONGINT; theChannel: CMChannel; async: BOOLEAN; completor: 
ProcPtr; timeout: LONGINT; flags: CMFlags): CMErr; 

theBuffer specifies the buffer from which the connection gets the data to write. 

toWrite specifies the number of bytes to be written. If your application calls this 
routine synchronously, the connection tool returns the actual number of bytes it wrote in 
toWrite . Your application can call cMstatus to see if an asychronous write is 
pending. If your application calls this routine asynchronously, the asyncCount field of 
the connection record contains the actual number of bytes written when the completion 
routine is called. 

theChannel specifies the channel on which writing takes place. Acceptable values are as 
follows: 

CONST 

cmData = $00000001; 

cmCntl = $00000002; 

cmAttn = $00000004; 

async specifies whether or not the request is asynchronous. If your application makes 
an asynchronous request, CMWrite returns cmNoErr immediately. 

completor specifies the completion routine to be called upon completion of an 
asynchronous write request. Completion routines are discussed in greater detail later in 
this chapter in the section “Completion Routines.” 

timeout Specifies a time period, in ticks, within which the connection tool must 
complete the write operation. If it does not complete within the specified period, a 
timeout error occurs. For no timeout, use -1. If your application specifies 0, the 
connection tool writes as many bytes, up to towrite bytes, as it can in one write 
attempt. Some connection tools ignore this parameter. 
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flags indicates whether or not the connection tool should send an end-of-message 
indicator. An end-of-message indicator needs to be supported by the particular 
communications protocol being used; if an end-of-message indicator is not supported by 
the connection protocol, your application should ignore this field. 

CONST 

cmFlagsEOM = $0001; 


CMAddSearch 


Adding a data stream search 

When an application is reading data with CMRead, you can have the data stream searched 
for one or more patterns of bytes. To perform the search, your application must pass 
information to the Connection Manager, such as the connection on which the data stream 
is coming in and the sequences of bytes for which to look. CMAddSearch tells the 
Connection Manager to perform the search, passing it search-specific information as well. 
Each time your application calls CMAddSearch, the Connection Manager searches for an 
additional sequence of bytes. 


Function CMAddSearch(hConn: ConnHandle; theString: Str255; flags: 

CMSearchFlags; callBack: ProcPtr): LONGINT; 

Description The value CMAddSearch returns is a search reference number that is used by the 

CMRemoveSearch routine (described later in this section). If CMAddSearch returns 
-1, the connection tool did not successfully add the search. Your application uses the 
search reference number to distinguish among different searches that may be occurring 
simultaneously on the same connection. 

flags is a field that describes the search to be performed. The appropriate values are as 
follows: 

TYPE 

CMSearchFlags = INTEGER; 

CONST 

cmSearchSevenBit = $0001; 

If cmSearchSevenBit is on, the Connection Manager matches only the low 7 
bits of a character; otherwise, it matches all 8 bits. The other bits of flags are 
reserved for Apple Computer 

callBack is a pointer to a routine the Connection Manager will Call during CMRead in 
the event that the connection tool finds a match. The calling conventions for the call¬ 
back procedure are given in the next section. 
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MySearchCallBack 

what to do when there’s a match 


Procedure 

The Connection Manager will pass control to a search call-back procedure in the event that 
the connection tool finds a match in the incoming data stream. This routine may be called 
at interrupt level. 

MySearchCallBack(hConn: ConnHandle; matchPtr: Ptr; refNum: 
LONGINT); 

Description 

matchPtr points to the last matched character in the read buffer. 

MySearchCallBack uses the Search reference number cMAddsearch returns; your 
application should pass this value in refNum. 

♦ Note: The Connection Manager calls MysearchcaiiBack when a read completes, and 
therefore might be called at interrupt level. If your application makes asynchronous calls, 
MySearchCallBack has the same restrictions as the standard Device Manager 
completion routines. 


CMRemoveSearch 


Stopping a data stream search 

CMRemoveSearch reitioves the Search with the specified reference number for the 


Procedure 

specified connection record. This routine can not be called at interrupt level (making it 
impossible for MySearchCallBack to Call this routine). 

CMRemoveSearch(hConn: ConnHandle; refNum: LONGINT); 

Description 

refnum is the Search reference number returned by CMAddsearch. 


CMClearSearch 


Clearing all data stream searches 

CMClearSearch removes all searches associated with the specified connection record. 


Procedure 

CMClearSearch (hConn: ConnHandle); 

Description 

CMClearSearch cannot be Called from interrupt level. 
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Handling events 

The Connection Manager event-processing routines provide useful extensions to the Macintosh 
Toolbox Event Manager. This section explains the four routines the Connection Manager provides. 
See “Other Events” in Chapter 2 for sample code showing how an application can determine if an 
event needs to be handled by one of these routines. 

CMActivate 


Activate events 


Procedure 

CMActivate processes an activate or deactivate event (for instance, installing or 
removing a custom tool menu) for a window associated with the connection. 

CMActivate(hConn: ConnHandle; activate: BOOLEAN); 

Description 

If activate is TRUE , the connection tool processes the activate event. Otherwise, it 
processes a deactivate event. 

CMRe Slime 



Resume events 



CMResume processes a resume or suspend event for a window associated with the 
connection. 

Procedure 

CMResume(hConn: ConnHandle; resume: BOOLEAN); 

Description 

If resume is TRUE , the connection tool processes a resume event. Otherwise, it 
processes a suspend event. 


CMMenu 


Menu events 

Your application must call CMMenu when the user chooses an item from a menu that is 
installed by the connection tool. 

Function 

CMMenu(hConn: ConnHandle; menuID: INTEGER; item; INTEGER): 

BOOLEAN; 

Description 

CMMenu returns false if the connection tool did not handle the menu event. CMMenu 
returns true if the connection tool did handle the menu event. 
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CMEvent 


Other events 


Procedure 

Description 


When your application receives an event, it should check if the ref con of the window 
is a tool’s connHandie . Such an event occurs, for example, when the user clicks a button 
in a dialog box displayed by the connection tool. If it does belong to a connection tool’s 
window, your application can call cMEvent. 

CMEvent(hConn: ConnHandie; theEvent: EventRecord); 

A window (or dialog box) created by a connection tool has a connection record handle 
stored in the refCon field for wlndowRecord. 
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Localizing configuration strings 

The Communications Toolbox provides two routines that make it easier to localize configuration strings. 

CMIntlToEnglish 


Translating into English 

CMIntlToEnglish conveits a Configuration string, which is pointed to by 


Function 

inputPtr, to an American English configuration string pointed to by outputptr. 

CMIntlToEnglish(hConn: ConnHandle; inputPtr: Ptr; VAR 
outputPtr: Ptr; language: INTEGER): OSErr; 

Description 

The function returns an operating-system error code if any internal errors occur. 

The connection tool allocates space for outputptr. Your application is 
responsible for disposing of the pointer with oisposPtr when done with it. 

language specifies the language from which the string is to be converted. 

Valid values for this field are shown in the description of the Script Manager in 

Inside Macintosh, Volume V. If the language specified is not supported, this 
routine returns cmNoErr, but outputptr is nil. 


CMEnglishToIntl 


Translating from English 

CMEnglishToIntl converts an American English configuration string, which is 


Function 

pointed to by inputPtr, to a configuration string pointed to by outputptr. 

CMEnglishToIntl(hConn: ConnHandle; inputPtr: Ptr; VAR 
outputptr: Ptr; language: INTEGER): OSErr; 

Description 

The function returns an operating-system error code if any internal errors occur. 

The connection tool allocates space for outputptr; your application is 
responsible for disposing of the pointer with oisposPtr when done with it. 

language specifies the language to which the string is to be converted. 

Valid values for this field are shown in the description of the Script Manager in 

Inside Macintosh, Volume V. If the language specified is not supported, 
cmNoErr is Still returned, but outputptr is nil. 
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Miscellaneous routines 

The routines described in this section perform a variety of tasks. 

CMGetToolName 

Getting the name of a tool 

CMGetToolName retums in name the name of the tool specified by procio. 
Procedure CMGetToolName(procIO: INTEGER; VAR name: Str255); 

Description If procio references a connection tool that does not exist, the Connection Manager 

sets name to an empty string. 


CMSetRefCon 

Setting the connection record’s reference constant 

CMSetRefCon sets the connection record’s refcon field to the specified value. It is 
very important that your application use this routine to change the value of the reference 
constant, instead of changing it directly. 

Procedure CMSetRefCon(hConn: ConnHandle; refCon : LONGINT); 


CMGetRefCon 

Getting the connection record’s reference constant 

CMGetRefCon rctums the connection record’s reference constant. 
Function CMGetRefCon(hConn: ConnHandle): LONGINT; 
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CMSetUserData 


Setting the userOata field 

CMSetUserData scts the connection record’s useroata field to the specified value. 
It is very important that your application use this routine to change the value of the 
userData field, instead of changing it directly. 

Procedure CMSetUserData(hConn: ConnHandle; userData: LONGINT); 


CMGetUserData 

Getting the userData field 

CMGetUserData retums the connection record’s userData field. 
Function CMGetUserData(hConn: ConnHandle): LONGINT; 


CMGetVersion 

Getting 'vers' resource information 

CMGetversion retums a handle to a relocatable block, which contains the information 
in the connection tool’s ' vers ' resource with ID=1. Your application is responsible for 
disposing of the handle when done with it. 

♦ Note: The handle returned is not a resource handle. 


Function CMGetVersion{hConn:ConnHandle): Handle; 


CMGetCMVersion 

Getting the Connection Manager version number 

CMGetCMVersion retums the version number of the Connection Manager. 
Function CMGetCMVersion: INTEGER; 

Description The version number of the Connection Manager described in this document is: 

CONST 

curCMVersion = 1; 
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Completion routines 

This section describes the syntax and conventions that apply to completion routines in your 
application. 

MyCompletion 


Writing a completion routine 

The completion routine has the same restrictions as do standard Device Manager 


Procedure 

completion routines. For example, your routine should not allocate memory. 

MyCompletion(hConn: ConnHandle); 

Description 

when the Connection Manager calls MyCompletion, the errcode field of the 
connection record contains the appropriate error code. The asynccount field of the 
connection record contains the actual number of bytes read or written. Because the 
errcode field of the connection record is used by all of the Connection Manager 
routines, it contains the error code for the asynchronous operation only during execution 
of MyCompletion. 
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Quick reference 

This section provides a reference to Connection Manager routines and data structures. At the end of 
this section is a listing of routine selectors for programming in assembly language. 

Routines 

Connection Manager routines See page 

CMAbort(hConn: ConnHandle): CMErr; 49 

CMAccept(hConniConnHandle; accept:BOOLEAN): CMErr; 52 

CMActivate(hConn: ConnHandle; activate: BOOLEAN); 61 

CMAddSearch(hConn: ConnHandle; theString: Str255; 59 

flags: CMSearchFlags; callBack: ProcPtr): LONGINT; 

CMBreak(hConn: ConnHandle; duration: LONGINT; async: 53 

BOOLEAN; completor: ProcPtr); 

CMChoose(VAR hConn:ConnHandle; where: Point; 41 

idleProc:ProcPtr): INTEGER; 

CMClearSearch(hConn: ConnHandle); 60 

CMClose(hConn: ConnHandle; async: BOOLEAN; completor: 49 

ProcPtr; timeout: LONGINT; now: BOOLEAN): CMErr; 

CMDefault(VAR theConfig: Ptr; procID: INTEGER; 40 

allocate: BOOLEAN); 

CMDispose(hConn: ConnHandle); 50 

CMEnglishToIntl(hConn: ConnHandle; inputPtr: Ptr; VAR 63 

outputPtr: Ptr; language: INTEGER): OSErr; 

CMEvent(hConn: ConnHandle; theEvent: EventRecord); 62 

CMGetCMVersion: INTEGER; 65 

CMGetConfig(hConn: ConnHandle): Ptr; 47 

CMGetConnEnvirons (hConn : ConnHandle; VAR 54 

theEnvirons : ConnEnvironRec) : CMErr; 

CMGetToolName(procID: INTEGER; VAR name: Str255); 64 

CMGetProcID(name: Str255): INTEGER; 37 

CMGetRefCon(hConn: ConnHandle): LONGINT; 64 

CMGetUserData(hConn: ConnHandle): LONGINT; 65 

CMGetVersion(hConn:ConnHandle):Handle; 65 

CMIdle(hConn: ConnHandle); 50 

CMIntlToEnglish(hConn: ConnHandle; inputPtr: Ptr; VAR 63 

outputPtr: Ptr; language: INTEGER): OSErr; 
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Connection Manager routines 


See page 


CMIOKill(hConn: ConnHandle; which: INTEGER): CMErr; 52 

CMListen(hConn: ConnHandle; async: BOOLEAN; 50 

completor: ProcPtr; timeout: LONGINT): CMErr; 

CMMenu(hConn: ConnHandle; menuID: INTEGER; item: 61 

INTEGER): BOOLEAN; 

CMNew(procID : INTEGER; flags : CMRecFlags; 38 

desiredSizes : CMBufferSizes; refCon : LONGINT; 
userData : LONGINT) : ConnHandle; 

CMOpen(hConn: ConnHandle; async: BOOLEAN; completor: 48 

ProcPtr; timeout: LONGINT): CMErr; 

CMRead(hConn: ConnHandle; theBuffer: Ptr; VAR toRead: 56 

LONGINT; theChannel: CMChannel; async: BOOLEAN; 
completor: ProcPtr; timeout: LONGINT; VAR flags: 

CMFlags): CMErr; 

CMRemoveSearch(hConn: ConnHandle; refNum: LONGINT); 60 

CMReset(hConn: ConnHandle); 53 

CMResume(hConn: ConnHandle; resume: BOOLEAN); 61 

CMSetConfig(hConn: ConnHandle; thePtr: Ptr): INTEGER; 47 

CMSetRefCon(hConn: ConnHandle; refCon: LONGINT); 64 

CMSetupCleanup(procID: INTEGER; theConfig: Ptr; 45 

count: INTEGER; theDialog: DialogPtr; VAR 
magicCookie: LONGINT); 

CMSetupFilter(procID: INTEGER; theConfig: Ptr; 44 

count:INTEGER; theDialog: DialogPtr; VAR theEvent: 
EventRecord; VAR theltem: INTEGER; VAR magicCookie: 

LONGINT): BOOLEAN; 

CMSetupItem(procID: INTEGER; theConfig: Ptr; count: 45 

INTEGER; theDialog: DialogPtr; VAR theltem: INTEGER; 

VAR magicCookie: LONGINT); 

CMSetupPostflight(procID:INTEGER); 46 

CMSetupPreflight(procID: INTEGER; VAR magicCookie: 43 

LONGINT): Handle; 

CMSetupSetup(procID: INTEGER; theConfig: Ptr; count: 44 

INTEGER; theDialog: DialogPtr; VAR magicCookie: 

LONGINT); 

CMSetUserData(hConn: ConnHandle; userData: LONGINT); 65 

CMStatus(hConn: ConnHandle; VAR sizes: CMBufferSizes; 51 

VAR flags: CMStatFlags): CMErr; 

CMValidate(hConn: ConnHandle): BOOLEAN; 40 
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Connection Manager routines 


See page 


CMWrite(hConn: ConnHandle; theBuffer: Ptr; VAR 58 

toWrite: LONGINT; theChannel: CMChannel; async: 

BOOLEAN; completor: ProcPtr; timeout: LONGINT; flags: 

CMFlags): CMErr; 

InitCM : CMErr; 36 

Routines in your application See page 

MySearchCallBack(hConn: ConnHandle; matchPtr: Ptr; 60 

refNum: LONGINT); 

MyCompletion(hConn: ConnHandle); 66 


Connection Record 

TYPE 


ConnHandle 

= 

'"ConnPtr; 

ConnPtr 

= 

'"ConnRecord; 

ConnRecord 

= 

RECORD 

procID 


INTEGER; 

flags 

; 

CMRecFlags; 

errCode 

: 

CMErr; 

refCon 

: 

LONGINT; 

userData 


LONGINT 

defProc 


ProcPtr; 

config 


Ptr; 

oldConfig 

: 

Ptr; 

reservedO 


LONGINT; 

reservedl 


LONGINT; 

reserved2 


LONGINT; 

cmPrivate 

: 

Ptr; 

bufferArray 

: 

CMBuf fers; 

bufSizes 

: 

CMBufferSizes; 

mluField 

: 

LONGINT; 

asyncCount 

; 

CMBufferSizes; 


END; 
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Constants and data types 


TYPE 

CMBufFields=( 

cmDataIn, 

cmDataOut 

cmCntlln 

cmCntlOut 

cmAttnIn 

cmAttnOut 

cmRsrvIn 

cmRsrvOut); 


CMBuffers 


ARRAY[CMBu fFie1ds] OF 


CMBufferSizes = 

ARRAY[CMBufFields] 

Connection Environment Record 


TYPE 


ConnEnvironRecPtr 

'^ConnEnvironRec 

ConnEnvironRec 

RECORD; 

version 

INTEGER; 

baudRate 

LONGINT; 

dataBits 

INTEGER; 

channels 

CMChannel; 

swFlowControl 

BOOLEAN; 

hwFlowControl 

BOOLEAN; 

flags 

CMFlags; 


END; 


Ptr; 

LONGINT; 


TYPE 





CMFlags 

* 

INTEGER 

CONST 





cmFlagsEOM 


1; 


TYPE 

CMChannel: INTEGER; 
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CONST 


cmData 

= 

$00000001 

cmCntl 

= 

$00000002 

cmAttn 

= 

$00000004 

cmDataClean 

s 

$00000100 

cmCntlClean 

3S 

$00000200 

cmAttnClean 

= 

$00000400 

cmNoMenus 

= 

$00010000; 

cmQuiet 


$00020000; 


Version constants 

CONST 

curConnEnvRecVers = 0; 

curCMVersion = 1; 


Connection record flags bit masks 

TYPE 

CMRecFlags = LONGINT; 


CONST 


cmData 

= 

$00000001 

cmCntl 

= 

$00000002 

cmAttn 


$00000004 

cmDataClean 


$00000100 

cmCntlClean 

= 

$00000200 

cmAttnClean 

= 

$00000400 

cmNoMenus 

= 

$00010000 

cmQuiet 

= 

$00020000 

Search flags 



TYPE 




CMSearchFlags * INTEGER; 

CONST 

cmSearchSevenBit = $0001; 
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Values returned by CMChoose 


CONST 

chooseDisaster = -2 
chooseFailed = -1 
chooseAborted = 0 
chooseOKMinor = 1 
chooseOKMajor = 2 
chooseCancel = 3 


Connection status flags 

TYPE 

CMStatFlags 

CONST 

cmStatusOpening 

cmStatusOpen 

cmStatusClosing 

cmStatusDataAvail 

cmStatusCntlAvail 

cmStatusAttnAvail 

cmStatusDRPend 

cmStatusDWPend 

cmStatusCRPend 

cmStatusCWPend 

cmStatusARPend 

cmStatusAWPend 

cmStatusBreakPending 

cmStatusListenPend 

cmStatusIncomingCallPresent 


LONGINT; 


$00000001 

$00000002 

$00000004 

$00000008 

$00000010 

$00000020 


{tool is opening connection} 
{connection is open} 

{tool is closing connection} 
{data present on data channel} 
{data present on cntl channel} 
{data present on attn channel} 


$00000040 

{data 

$00000080 

{data 

$00000100 

{cntl 

$00000200 

{cntl 

$00000400 

{attn 

$00000800 

{attn 


read pending} 
write pending} 
read pending} 
write pending} 
read pending} 
write pending} 


$00001000; {tool is breaking the connection} 
$00002000; {tool is "listening" for data} 
$00004000; {call waiting for tool to handle} 


Errors 


TYPE 

CMErr 

CONST 

cmGenericError = 

cmNoErr = 

cmRejected = 

cmFailed = 

cmTimeOut = 

cmNotOpen = 

cmNotClosed = 

cmNoRequestPending = 
cmNotSupported = 

cmNoTools = 


OSErr; 


-1 

0 

1 

2 

3 

4 

5 

6 

7 

8 
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Connection Manager routine selectors 

♦ Assembly note: The Communications Toolbox routines are accessed via a Macintosh Operating 
System trap, ao contains a pointer to the routine parameters. You can call each of the 
Communications Tooolbox routines with a macro that has the same name as the routine 
preceded by an underscore. When expanded, these macros put the routine selector onto the 
stack, set ao to point to the selector, invoke the trap macro _comTooiTrap ($ao8b) , and 
finally pop the routine selector back off the stack. It is your application’s responsibility to 
remove the parameters. 


CMAbort 

.EQU 

271 

CMIOKill 

.EQU 

297 

CMAccept 

.EQU 

269 

CMListen 

.EQU 

268 

CMActivate 

.EQU 

275 

CMMenu 

.EQU 

277 

CMAddSearch 

.EQU 

294 

CMNew 

.EQU 

264 

CMBreak 

.EQU 

293 

CMOpen 

.EQU 

267 

CMChoose 

.EQU 

292 

CMRead 

.EQU 

273 

CMClearSearch 

.EQU 

296 

CMRemoveSearch 

.EQU 

295 

CMClose 

.EQU 

270 

CMReset 

.EQU 

278 

CMDefault 

.EQU 

280 

CMResume 

.EQU 

276 

CMDispose 

.EQU 

265 

CMSetConfig 

.EQU 

285 

CMEnglishToIntl 

.EQU 

287 

CMSetRefCon 

.EQU 

258 

CMEvent 

.EQU 

298 

CMSetupCleanup 

.EQU 

283 

CMGetCMVersion 

.EQU 

289 

CMSetupFilter 

• EQU 

290 

CMGetConfig 

.EQU 

284 

CMSetupItem 

.EQU 

282 

CMGetConnEnvirons 

.EQU 

300 

CMSetupPostflight 

.EQU 

299 

CMGetProcID 

.EQU 

263 

CMSetupPreflight 

.EQU 

291 

CMGetRefCon 

.EQU 

259 

CMSetupSetup 

.EQU 

281 

CMGetToolName 

.EQU 

262 

CMSetUserData 

.EQU 

260 

CMGetUserData 

.EQU 

261 

CMStatus 

.EQU 

272 

CMGetVersion 

.EQU 

288 

CMValidate 

.EQU 

279 

CMIdle 

.EQU 

266 

CMWrite 

.EQU 

274 

CMIntlToEnglish 

.EQU 

286 

InitCM 

.EQU 

257 
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Chapter 4 Terminal Manager 





















































































THIS CHAPTER describes the Terminal Manager, the Communications 
Toolbox manager that allows applications to perform terminal emulation 
independent of a specific type of terminal. This chapter starts out by 
describing fundamental concepts about the Terminal Manager. It goes on to 
describe the terminal emulation window and the data structure most 
important to the Terminal Manager, the terminal record. Next, this chapter 
presents a detailed functional description of each routine provided by the 
Terminal Manager. It then describes the routines that need to be in your 
application. At the end of the chapter, you’ll find a quick reference to routines, 
data structures, and routine selectors for programming in assembly language. 

In this chapter, the term your application refers to the application you are 
writing for the Macintosh, which will implement communications services 
for users. Be careful not to confuse the services your application provides 
with the services that tools provide. 

To use terminal tools in an application, you need to be familiar with 

■ the Resource Manager (described in Inside Macintosh, Volumes I, IV, V) 

■ the QuickDraw™ (described in Inside Macintosh, Volumes I, V) 

■ the Event Manager (described in Inside Macintosh, Volumes I, IV, V) 

■ the Scrap Manager (described in Inside Macintosh, Wohmel) 

■ the Dialog Manager (described in Inside Macintosh, Volumes I, IV, V) 

■ the Connection Manager (described in Chapter 3 of this document) 
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About the Terminal Manager 

By using Terminal Manager routines, your application can implement a terminal emulation without 
having to take into account the characteristics of any one type of terminal. Terminal tools, which 
are discussed in Chapter 10, are responsible for implementing the characteristics of specific terminal 
types. 

The Terminal Manager provides a generic terminal emulation that is best described with an 
example. Suppose your application needs to tell a mainframe at the other end of an existing data 
connection that the user has typed the letter a. Your application detects that the user has pressed a 
key, and passes this event on to the Terminal Manager by calling the TMKey routine. The 
Terminal Manager passes this event on to a previously selected terminal tool. The terminal tool 
figures out the appropriate value to transmit for a and sends it out on the data connection. This 
example, of course, is a very simple one. But it is meant to give you a general feel for what goes on 
inside the Terminal Manager. The rest of this chapter goes into much more detail. 

Figure 4-1 shows the data flow into and out of the Terminal Manager. 


■ Figure 4-1 Data flow into and out of the Terminal Manager 



The most important data structure maintained by the Terminal Manager is the terminal record, 
which is where all the specifics of a terminal emulation are stored. For example, the terminal record 
might show that your application is emulating a VT320™ terminal, and that the Terminal Manager 
should try to cache the terminal window before clearing it. 
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One important aspect of the terminal record is that it allows you to write routines independent 
of specific terminal characteristics. For instance, when an application wants to transmit a keystroke 
to a host computer, it tells the Terminal Manager to transmit the keystroke, and the terminal tool 
figures out exacdy how to transmit the keystroke for a specific type of terminal. 

Another important aspect of the terminal record is that it allows for multiple instances of the 
same tool. This means that the same tool can be used by different processes at the same time, as in 
a MultiFinder environment, or by different threads in a given application. The terminal record is 
described in greater detail later in this chapter. 

Besides providing access to basic terminal emulation services, the Terminal Manager includes 
routines that make it easy for your application to configure a terminal tool, either by presenting the 
user with a dialog box or by interfacing directly with a scripting language. The Terminal Manager 
also contains routines that make it easier for you to localize your applications in other languages. 

You can use the Terminal Manager in conjunction with other Communications Toolbox 
managers to create a communications application with basic connection, terminal emulation, and 
file transfer capabilities. Or, you an use the Terminal Manager with some other connection service 
or file transfer service instad of the Connection Manager and File Transfer Manager. You an also 
write your own terminal tool for the Terminal Manager to use (this procedure is discussed in 
Chapters 8 and 10). Regardless of which method you choose, your application should be able to 
handle different terminal tools such that users can change tools and still be able to use your 
program. 


The terminal emulation window 

The Terminal Manager provides terminal tools with a terminal emulation window. In addition to tide 
bar, scroll bars, and other standard user interface elements, the terminal emulation window has two 
major parts: the terminal emulation region and the cache region. Figure 4-2 shows these parts. 


Figure 4-2 A terminal emulation window 


I Terminal emulation uiindoui 


cache region 


terminal emulation region 


O 




m. 
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The terminal emulation region 

The terminal emulation region is the area of the terminal window in which the terminal tool 
displays data in a manner that emulates a specific terminal. Terminal tools use a tenninal 
emulation buffer to store the data displayed in the terminal emulation region. Your application 
and the terminal tools exchange this data through a TermoataBiock, which is an extensible data 
structure that handles text and graphics information. For text terminals, the TermoataBiock 
describes a line of text in the terminal emulation region. For graphics terminals, the 
TermoataBiock describes a picture in the terminal emulation region. The format of 
TermoataBiock is as follows: 

TYPE 

TermDataBlockH 
TermDataBlockPtr 
TermDataBlock 
flags 
theData 
auxData 
reserved 

END; 

flags describes the data in the TermoataBiock. Valid values are: TMTextTerminai and 
TMGraphicsTerminal. 

theoata is a handle to data, which is text characters for text terminals and a QuickDraw picture 
for graphics terminals. Your application can get the sixe of theoata by calling 

GetHandleSize(theData). 

auxoata and reserved are reserved by Apple Computer Do not use them or your application 
may not work in the future. 


'^TermDataPtr; 

'"TermDataBlock; 

RECORD 

TMTermTypes; 

Handle; 

Handle; 

LONGINT; 


The cache region 

The cache region is an optional area in the window, which your application can use to display data 
that scrolls off the top of the terminal emulation region. Because terminal tools do not maintain 
this area of the terminal emulation window, your application must provide all the necessary code if 
you want a cache region. 
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The terminal record 


The terminal record contains information that describes a terminal emulation, as well as pointers to 
Terminal Manager internal data structures. The Terminal Manager uses this information to 
“translate” the protocol-independent routines used by an application or tool into a service 
implemented according to a specified terminal emulation. Most of the fields in the terminal record 
are filled in when an application calls TMNew, described later in this chapter. 

Because the context for a given terminal emulation is maintained in a terminal record, an 
application can maintain more than one terminal emulation at the same time. All the application has 
to do is create a new terminal record every time it initiates a terminal emulation. 

A Important Your application, in order to be compatible with future releases of the 


Terminal Manager, should not directly manipulate the fields of the 
terminal record (with the exception of config and oidconfig). The 
Terminal Manager provides routines that applications and tools can use to 
change terminal record fields. These routines are discussed later in this 
chapter, a 


Terminal record data structure 


TYPE 


TermHandle 

TermPointer 

TermRecord 


procID 


^TermPointer 

^TermRecord; 

RECORD 

INTEGER 


flags 

errCode 


TMFlags; 
TMErr; 


userData 


refCon 


LONGINT; 

LONGINT; 


defProc 


ProcPtr 


config 
oldConfig 


Ptr; 

Ptr; 


environsProc 

reservedl 

reserved2 


ProcPtr; 

LONGINT; 

LONGINT; 
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tmPrivate : 

: Ptr; 

sendProc 

breakProc 

cacheProc 

clikLoop 

ProcPtr; 

ProcPtr; 

ProcPtr; 

ProcPtr; 

owner 

termRect 

viewRect 

visRect 

WindowPtr; 

Rect ; 

Rect; 

Rect; 

lastidle ; 

: LONGINT; 

selection : 

selType : 

: TMSelection; 

: TMSelTypes; 

mluField : 

END; 

LONGINT; 

procID 

prociD is the terminal tool id. This value is dynamically assigned by the Terminal Manager when 
your application calls TMCetProciD. 

flags 

flags is a bit field with the following masks: 

CONST 

tminvisibie 

tmSaveBeforeClear 

tmNoMenus 

tmAutoScroii 

= $00000001; 

$00000002; 

= $00000004; 

$00000008; 

TYPE 

TMFlags : 

LONGINT; 


If your application sets tminvisibie, the Terminal Manager maintains a terminal emulation 
but does not display it. Your application can use the terminal emulation and cache region to create 
some other presentation service, instead of a terminal emulation. 

If your application sets tmsaveBeforeciear, the terminal tool will try to cache the entire 
terminal emulation region in response to any dear-screen operation. Clear-screen operations are 
generated from a user’s request, a clear-screen character sequence, or a terminal-reset character 
sequence. 

If your application sets tmNoMenus, the terminal tool will not put up any custom menus. 

If your application sets tmAutoScroii , the terminal tool will automatically scroll the 
terminal emulation window (if necessary) while the user is highlighting a selection. 
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errCode 

The Terminal Manager does not use errCode; it is included in this version (version 1.0) of the 
terminal record for reasons of historical preservation. Your application must not use this field. 

refCon 

refCon is a LONGiNT that your application can use. 

userData 

userData is a LONGINT that your application can use. 

defProc 

defProc is a pointer to the main code resource of the terminal tool that will implement the 
specifics of the terminal emulation. The terminal tool’s main code resource is of type ' tdef'. 

config 

con fig is a pointer to a data block that is private to the terminal tool. 

Your application can store the contents of config to save the state of a terminal in a 
document. The structure, size, and contents of the configuration record are set by the tool. Your 
application can determine the size of the configuration record by calling GetPtrsize, overwrite 
its contents using BiockMove, and validate the contents with TMVaiidate. 

Your application can use TMGetconfig and TMSetconfig to manipulate fields in this 
record. For details, read “Interfacing with a Scripting Language,” later in this chapter. 

You can find a description of config from a terminal tool perspective in Chapter 8. 

oldConfig 

oidconf ig is a pointer to a data block that is private to the terminal tool and contains the most 
recently saved version of config. Your application is responsible for setting oidconfig when 
the user saves a session document. 

environs?roc 

environsProc is a pointer to a routine in your application that the terminal tool can call to 
obtain a record describing the connection environment. A more detailed description of 
environsProc appears later in this chapter in “Routines That Must Be in Your Application.” 

reservedl and reserved2 

reservedi and reservedz are reserved for the Terminal Manager. Your application must not 
use this field. 
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tmPrivate 

tmPrivate is a pointer to a data block that is private to the terminal tool. Your application must 
not use this field. 

sendProc 

sendProc is a pointer to a routine your application calls when it needs to send data to another 
application. A more detailed description of sendProc appears later in this chapter in “Routines 
That Must Be in Your Application.” 

breakProc 

breakProc is a pointer to a routine in your application that performs a break operation. The 
effect the break has depends on the terminal emulation being used. A more detailed description of 
breakProc appears later in this chapter in “Routines That Must Be in Your Application.” 

cacheProc 

cacheProc is a pointer to a routine in your application that saves lines that scroll off the top of 
the terminal emulation region. The terminal tool also uses this routine to save the terminal screen 
before a dear-screen operation (if the TMSaveBeforeciear bit is set in the flags field of 
the terminal record). A more detailed description of cacheProc appears later in this chapter in 
“Routines That Must Be in Your Application.” 

clikLoop 

clikLoop is a pointer to a routine in your application that handles mouse clicks. The terminal tool 
calls the click loop repeatedly when the user is clicking or dragging an object. A more detailed 
description of this routine appears later in this chapter in “Routines That Must Be in Your 
Application.” 

owner 

owner is a pointer to the grafPort in which your application displays the terminal emulation. 

termRect 

termRect is the poitRect of the current window, minus the scroll bars. This portRect represents 
the boundaries of the terminal emulation region. Figure 4-3 shows how termRect relates to the 
terminal emulation window. 


♦ Note: Your application can display the terminal emulation region in an area that is smaller 
than termRect , but it must not display the combination of the cache region and terminal 
emulation region in an area larger than termRect. 
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viewRect 

viewRect is a subsct of termRect; it represents the boundaries of the visible part of the 
terminal emulation region. Figure 4-3 shows how viewRect relates to the terminal emulation 
window. 

■ Figure 4-3 Bounds of viewRect and termRect 
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visRect 

visRect is a rectangle that represents the currently visible rows and columns in the terminal 
emulation region (for text terminals). It has the same dimensions as viewRect, but is defined by 
coordinates that represent rows and column numbers. Numbering of rows and columns begins 
with the number 1. 

visRect. top is the top visible line, and visRect .left is the leftmost visible column in 
the terminal emulation region. visRect.bottom is the bottom visible line, and 
VisRect. right is the rightmost visible column in the terminal region. These values are used by 
the application to determine scroll-bar values. 

lastIdle 

lastidie is the last time (in ticks) that the idle procedure was called for the specified terminal 
record. 
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selection 

selection is a data structure that describes the extent of the current selection in the terminal 
emulation window. Since selection an describe either a rectangle or a region, it describes the 
selection in one of two kinds of data structures: a Rect or a RgnHandie. The format of the 
TMSeiection data Structure is as follows: 

TYPE 

TMSeiection = 

CASE INTEGER OF 
1 : ( 

selRect : 

) / 

2 : ( 

selRgnHandle : 
filler : 

) ; 

END; 

seiRect is of type Rect and describes the rectangle that has been selected. On a text 
terminal, it contains the row/column pairs, with counting beginning at 1. On a graphia terminal, it 
contains pixel coordinates, with (1,1) being the topLeft comer of the terminal region. 

On a graphics terminal, if the selection is a MacPaint®-style lasso, selection is a 
selRgnHandle that represents the selection region. 


RECORD 


Rect; 


RgnHandie; 

LONGINT; 


selType 

seiType is a field that further describes a selection; it indicates the highlighting mode that is used 
to show the selection. Valid values are as follows: 


CONST 

selTextNormal = 

$0001; 

seiTextBoxed = 

$0002; 

selGraphicsMarquee = 

$0004; 

selGraphicsLasso = 

$0008; 

TYPE 

TMSelTypes = 

INTEGER; 


Figure 4-4 and Figure 4-5 show that even though two selections may have the same coordinates, 
different values for seiType yield different highlighting results. Figure 4-4 shows the text- 
selection mode seiTextNormai. Figure 4-5 shows a text selection in seiTextBoxed mode. 
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■ Figure 4-4 The text selection mode 
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Figure 4-5 The text selection mode 
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seiGraphicsMarquee is a Standard rectangular MacPaint-style marquee. 
seiGraphicsLasso is a Standard MacPaint-style lasso. Your application uses these types of 
highlighting with graphics terminals. 

mluField 

mluFieid is a LONGiNT that terminal tools use. Your appliation does not need to be 
concerned with this field. 
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Terminal Manager routines 

The sections describe the routines that tools and applications can use to access Terminal Manager 
services. Your application can not call these routines from interrupt level. 

Below is a listing of the routines described in this section in the order in which they are presented. 


InitTM / 88 

TMClearSearch / 103 

TMGetProcID / 88 

TMSetSelection / 104 

TMNew / 89 

TMGetSelect / 104 

TMDefault / 91 

TMActivate / 105 

invalidate / 91 

TMResume / 105 

TMChoose / 92 

TMMenu / 105 

TMSetupPreFlight / 94 

TMClick / 106 

TMSetupSetup / 95 

TMKey / 106 

TMSetupFilter / 95 

TMUpdate / 106 

TMSetupItem / 96 

TMEvent / 107 

TMSetupCleanup / 96 

TMIntlToEnglish / 108 

TMSetupPostflight / 97 

TMEnglishToIntl / 108 

TMGetConfig / 98 

TMGetToolName / 109 

TMSetConfig / 98 

TMSetRefCon / 109 

TMStream / 99 

TMGetRefCon / 109 

TMPaint / 99 

TMSetUserData / 110 

TMIdle / 99 

TMGetUserData / 110 

TMGetLine / 100 

TMGetVersion / 110 

TMScroll / 100 

TMGetTMVersion / 110 

TMClear / 100 

TMGetCursor / 111 

TMReset / 101 

TMDoTermKey / 111 

TMResize / 101 

TMCountTermKeys / 112 

TMDispose / 101 

TMGetlndTermKey / 112 

TMAddSearch / 102 

TMGetTermEnvirons / 112 

TMRemoveSearch / 103 
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Preparing for a terminal emulation 

Before your application can start a terminal emulation, it must initialize the Terminal Manager (by calling 
initTM), find out the procio of the tool it requires (by calling THGetProcio), create a terminal 
record (by calling tmnsw), and then configure the terminal tool (by restoring conf ig from a saved 
document; or by calling TMChoose, the terminal tool custom configuration routines, or TMSetconfig). 

InitTM 


Initializing the Terminal Mani^er 

InitTM initializes the Terminal Manager. Your application should call this routine after it 
calls the standard Macintosh Toolbox initialization routines. 

A Warning Your application must initialize the Communications Resource Manager (by 


Function 

calling initcRM) and then the Communications Toolbox Utilities (by calling 
initcTButiiities), whether or not it uses any of their calls, before it initializes the 
Terminal Manager, a 

InitTM: TMErr; 

Description 

InitTM returns an operating-system error code if appropriate. Valid values are: 

TYPE 

TMErr = OSErr; 

CONST 

tmGenericError = -1; 

tmNoErr = 0; 

tmNoTools = 8; 

Your application must check for the presence of the Communications Toolbox before 
calling this function. Sample code under “Determining Whether the Managers are Installed” 
in Appendix B shows you how your application can make this check. 

TMGetProcID 



Getting current prociD information 

Your application should call TMGetProcio just before creating a new terminal record. 


Function 

to find out the procio of a tool. 

TMGetProcID(name: Str255) : INTEGER; 

Description 

name specifies a terminal tool. If there is a terminal tool in the folder named 
CommMwtcdrtoMS FoWerwith the specified name, its procio is returned. If name 
references a nonexistent terminal tool, -1 is returned. 
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TMNew 


Creating a terminal record 

Once the Terminal Manager has been initialized, your application needs to call TMNew t o 
create a terminal record to describe the terminal emulation that is to take place. TMNew 
creates a new terminal record; fills in the fields it can, based on the parameters that were 
passed to it; and returns a handle to the new record in TermHandie. TMNew 
automatically makes two calls to TMOefauit (which is described later in this chapter) 
to fill in config and oidconf ig. The Terminal Manager then loads the terminal 
tool’s main definition procedure, moves it high in the current heap, and locb it. If an error 
occurs that prevents a new terminal record from being created (for example, running out 
of memory), TMNew passes back nil in TermHandie. 

Your application must set the current port to the terminal window before it calls 

TMNew. 


Function 


Description 


TMNew(termRect: Rect; viewRect: Rect; flags: TMFlags; procID: 
INTEGER; owner: WindowPtr; sendProc: ProcPtr; cacheProc: 
ProcPtr; breakProc: ProcPtr; clikLoop: ProcPtr; environsProc: 
ProcPtr; refCon: LONGINT; userData: LONGINT): TermHandie; 


termRect is a rectangle in local coordinates that represents the boundaries of the 
terminal emulation region. Your appliation initially sets this value by passing it as a 
parameter to TMNew. 

ViewRect is a subset of termRect, which the terminal tool can actually write into. 
Your application initially sets this value by passing it as a parameter to TMNew, but the 
terminal tool may resize it. 

flags is a bit field with the following masks: 


CONST 

tminvisible 
tmSaveBeforeClear 
tmNoMenus 
tmAutoScroll 


$ 00000001 ; 

$ 00000002 ; 

$00000004; 

$00000008; 


flags represents a request from your application for a level of service. 

Apple Computer has reserved the bits of flags that are not shown in this 
document. Do not use them, or your code may not work in the future. 

If your application sets tminvisible, the Terminal Manager maintains a terminal 
emulation but does not display it. Your application can use the terminal emulation and 
cache regions to create some other presentation service instead of a terminal emulation. 

If your application sets tmsaveBeforeciear, the terminal tool attempts to 
cache the entire terminal emulation region in response to any dear-screen operation. Clear- 
screen operations are generated from either a user’s request, a dear-screen character 
sequence, or a terminal-reset character sequence. 

If your application sets tmNoMenus, the terminal tool does not display any 
custom menus. 
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If your application sets tmAutoScroii , the terminal tool automatically scrolls the 
terminal emulation window (if necessary) while the user highlights a selection. 

prociD values are dynamically assigned by the Terminal Manager to tools at run time. 
Applications should not store procio values in “settings” files. Instead, they should 
store tool names, which can be converted to procio values with iMGetProcio. Use 
the ID that iMGetProcio returns for procio. 

owner is a pointer to the window in which your application is displaying the terminal 
emulation. If tminvisibie is FALSE, owner should be a grafPort that the terminal 
tool has control over. 

sendProc is a pointer to a routine the terminal tool calls when it needs to send data on a 
connection. A more detailed description of sendProc appears later in this chapter, in 
the section “Routines That Must Be in Your Application.” 

cacheProc is a pointer to a routine in your application that saves lines that scroll off 
the top of the terminal emulation region. This routine also saves the terminal screen 
before a dear-screen operation (if TMSaveBeforeciear is set). If your application 
does not have a cacheProc, specify nil in this field. A more detailed description of 
cacheProc appears later in this chapter in the section “Routines That Must Be in Your 
Appliation.” 

breakProc is a pointer to a routine in your application that performs some sort of 
break operation. The effect the break has depends upon the terminal emulation tool that 
your application is using. A more detailed description of breakProc appears later in this 
chapter in the section “Routines That Must Be in Your Application.” 

ciikLoop is a pointer to a routine in your application that is called when the mouse 
button is held down. The terminal tool calls the click loop repeatedly when users are 
clicking and dragging the mouse. A more detailed description of ciikLoop appears later 
in this chapter, in the section “Routines That Must Be in Your Application.” Specify nil 
in this field if your application has no ciikLoop procedure. 

environsProc is a pointer to a routine that the terminal tool calls when it requires 
information about the connection. See “Connection Manager Routines” in Chapter 3 for 
information about the cMGetconnEnvirons routine. 

userData and refcon are fields your application can use. 
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TMDefault 


Initializing the terminal record 



TMDefault fills the Configuration record pointed to by theconfig with the default 
configuration, which is specified by the terminal tool with the given prociD. TMNew 
calls this procedure automatically when it fills in the conf ig and oidconf ig fields 
in a new terminal record. 

Procedure 

TMDefault(VAR theConfig: Ptr; procID: INTEGER; allocate: 

BOOLEAN)/ 

Description 

If allocate is TRUE , the tool allocates space for theconfig in the current heap 
zone. 


invalidate 


Validating the terminal record 

invalidate performs an internal consistenqr check on the configuration and private 


Function 

data records of the terminal record. TMNew and TMSetconfig call this routine after 
they have created a new terminal record, to make sure that the record contains values 
identical to those specified by the terminal tool. 

invalidate(hTerm: TermHandle) : BOOLEAN; 

Description 

If the validation fails, the Terminal Manager returns true and the terminal tool fills the 
configuration record with default values by calling iMoefauit. 

Your application can call this routine after restoring a configuration, to verify that the 
terminal record contains the correct information, in a manner similar to that shown next. 

BlockMove (saveConf ig, hTerm .config,GetPtrSize (hTerm'^'^. conf ig) ) / 

IF TMValidate(hTerm) THEN BEGIN 
{validate failed} 

END 

ELSE BEGIN 

(validate succeeded} 

END 
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TMChoose 


Configuring a terminal tool 

An application can configure a terminal tool in one of three ways. The easiest and most 
straightforward way is by calling the TMChoose routine. This routine presents the user 
with a dialog box similar to the one shown in Figure 4-6. 

m Figure 4-6 The standard tool-settings dialog box 



The second way an application can configure a terminal tool is by presenting the user with 
a custom tool-settings dialog box. This method is much more difficult and involves 
calling six routines. The routines are described in the next section, “Custom Configuration 
of a Terminal Tool,” and “The Custom Tool-Settings Dialog Box” in Appendix B provides 
example code 

The third way your application can configure a terminal tool is by using the scripting 
language interface, described in “Interfacing with a Scripting Language,” later in this 
chapter. This method allows your application to bypass user interface elements. 

Function TMChoose(VAR hTerm: TermHandle; where: Point; idleProc: 

ProcPtr): INTEGER; 

Description where is the point specified in global coordinates, where the upper-left corner of the 

dialog box should appear. It is recommended that your application place the dialog as close 
to the upper-left comer of the screen as possible because the size of the dialog box varies 
from tool to tool. 

idleProc is a procedure with no parameters that the Terminal Manager will 
automatically call every time TMChoose loops through the setup dialog box filter 
procedure. Pass nil if your application has no idieProc. 
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TMChoose rctums One of the following values: 


CONST 


chooseDisaster 
chooseFailed 
chooseOKMinor 
chooseOKMajor 
chooseCancel 



ChooseDisaster means that the TMChoose operation failed, destroyed the 
terminal record, and returned nil in the terminal handle. 

ChooseFailed means that the TMChoose Operation failed and the terminal 
record was not changed. 

ChooseOKMinor means that the user clicked OK in the dialog box, but did not 
change the terminal tool being used. 

ChooseOKMa jor means that the user clicked OK in the dialog box and also changed 
the terminal tool being used. The Terminal Manager then destroys the old terminal handle 
by calling TMOispose, and returns a new terminal handle in hTerm. 

chooseCancel means that the user clicked Cancel in the dialog box. 
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TMSetupItem 


Processing custom tool-settings dialog box events 

TMSetupItem processes events for controls in the custom tool-settings dialog box. 


Procedure 

TMSetupItem(procID: INTEGER; theConfig: Ptr; count: INTEGER; 
theDialog: DialogPtr; VAR theltem: INTEGER; VAR magicCookie: 
LONGINT) ; 

Description 

prociD is the ID for the terminal tool being configured. Your application should use the 
same value for procio as it passed to TMSetupPreflight. 

theConfig is a pointer to the configuration record for the tool being configured. 

count is the number of the first item in the dialog item list appended to the dialog box. 

theDialog is the dialog box performing the configuration. 

theltem is the item clicked in the dialog box. This value can be modified and sent back. 

magicCookie is a pointer to private storage for the terminal tool. 


TMSetupCleanup 


Performing clean-up operations 

TMSetupCleanup disposes of any storage allocated in TMSetupPref light and 


Procedure 

performs other clean-up operations. If your application needs to shorten a dialog box, it 
should do so after calling this routine. 

TMSetupCleanup(prociD: INTEGER; theConfig: Ptr; count: INTEGER; 
theDialog: DialogPtr; VAR magicCookie: LONGINT); 

Description 

prociD is the ID for the terminal tool that is being configured. Your application should 
use the same value for prociD as it passed to TMSetupPref light. 

theConfig is a pointer to the configuration record for the tool being configured. 

count is the number of the first item in the dialog item list appended to the dialog box. 

theDialog is the dialog box performing the configuration. 

magicCookie is a pointer to private storage for the terminal tool. 
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TMSetupPostflight 


Closing the tool file 


TMSetupPostf light closes the tool file if it is not being used by any session. 
Procedure TMSetupPostflight(procID: INTEGER); 

Description prociD is the ID for the terminal tool that is being configured. Your application should 

use the same value for procio as it passed to TMSetupPreflight. 
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Manipulating selections 

The Terminal Manager provides two routines that make it easier for your application to manipulate 
selections in the terminal emulation window. TMSetseiection highlights a selection, and 
TMGetseiect retrieves the data in the selection. 

TMSetSelection 


Setting and highlighting selections 



TMSetseiection makes theSeiection the current selection. 

Procedure 

TMSetseiection(hTerm: TermHandle; theSeiection: TMSelection; 
selType: TMSelTypes)/ 

Description 

seiType determines the type of highlighting for the selection. Valid values are: 

TYPE 

TMSelTypes = INTEGER; 


CONST 

selTextNormal = $0001; 

selTextBoxed = $0002; 

selGraphicsMarquee = $0004; 

selGraphicsLasso = $0008; 


TMGetSelect 


Getting data from a selection 



TMGetSelect returns either the number of bytes in the selection, or an appropriate 
operating-system error code. 

Function 

TMGetSelect(hTerm: TermHandle; theData: Handle; VAR theType: 
ResType): LONGINT; 

Description 

If nothing is selected, TMGetSelect returns 0. Otherwise, it returns the size of the 
selected data. 

theData must be a handle to a block of size 0. TMGetSelect will resize this block as 
necessary. 

theType specifies the type of data this routine returns. If theType is text, 
theData is a handle to textual data. theType and theData may be passed direcdy 
to the Scrap Manager. 
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Handling events 

The Terminal Manager event-processing routines provide useful extensions to the Macintosh 
Toolbox Event Manager. This section explains the seven routines that the Terminal Manager 
provides. See “Other Events” in Chapter 2 for sample code showing how an application can 
determine if an event needs to be handled by one of these routines. 

TMActivate 


Activate events 


Procedure 

TMActivate processes an activate or deactivate event (for instance, installing or 
removing a custom tool menu) for a window associated with the terminal tool. 

TMActivate(hTerm: TermHandle; activate: BOOLEAN); 

Description 

If activate is TRUE, the terminal tool proccsscs an activate event. Otherwise, it 
processes a deactiveate event. 

TMRe Slime 



Resume events 



TMResume processes a resume or suspend event for a terminal window. Resume and 
suspend events are processed only if a tool has a custom menu to install or remove from 
the menu bar. 

Procedure 

TMResume(hTerm: TermHandle; resume: BOOLEAN); 

Description 

If resume is TRUE , then the terminal processes a resume event. Otherwise, it 
processes a suspend event. 


TMMenu 


Menu events 

Your application must call TMMenu when the user chooses an item from a menu that is 
installed by the terminal tool. 

Function 

TMMenu(hTerm: TermHandle; menuID: INTEGER; item: INTEGER): 

BOOLEAN; 

Description 

TMMenu retums FALSE if the terminal tool did not handle the menu event. TMMenu 
returns true if the terminal tool did handle the menu event. 
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TMClick 


Mouse events 


Procedure 

TMClick processes a mouseDown event in the terminal emulation region. The routine 
pointed to by ciikLoop, discussed in the section “Routines That Must Be in Your 
Application,” is called repeatedly by TMciick. 

TMClick(hTerm: TermHandle; theEvent: EventRecord); 

TMKey 



Keyboard events 


Procedure 

TMKey processes a keyoown or autoKey event. The terminal tool translates the 
keystroke into a sequence of bytes. The terminal tool then calls your application’s 
sendProc routine (discussed later in this chapter under “Routines That Must Be in Your 
Application.”) to transmit this sequence of bytes. 

TMKey(hTerm: TermHandle; theEvent: EventRecord); 

Description 

Your application can create its own event record for specific keyboard events by filling in 
the event record with the character code and -1 for the key code in the message field. 

TMUpdate 



Update events 



Your application will typically call TMUpdate between Beginupdate and 
EndUpdate. 

Procedure 

TMUpdate(hTerm: TermHandle; visRgn: RgnHandle); 

Description 

visRgn specifies the region to be updated. 
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TMEvent 


other events 


Procedure 

Description 


When your application receives an event, it should check if the ref con of the window 
is a tool’s hTerm. Such an event occurs, for example, when the user clicks a button in a 
dialog box displayed by the terminal tool. If it does belong to a terminal tool’s window, 
your application can call TMEvent. 

TMEvent(hTerm; TermHandle; theEvent; EventRecord); 

A window (or dialog box) created by a terminal tool has a terminal record handle stored in 
the refCon field for wlndowRecord. 
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Localizing configuration strings 

The Communications Toolbox provides two routines that make it easier to localize configuration 
strings. 

TMIntlToEnglish 


Translating into English 

TMIntlToEnglish conveits a Configuration string, which is pointed to by 


Function 

inputptr, to an American English configuration string pointed to by outputPtr. 

TMIntlToEnglish(hTerm: TermHandle; inputPtr: Ptr; VAR 
outputPtr: Ptr; language: INTEGER): OSErr; 

Description 

The function returns an operating-system error code if any internal errors occur. 

The terminal tool allocates space for outputPtr. Your application should dispose 
of this pointer when done with it. 

language specifies the language from which the string is to be converted. Valid 
values for this field are shown in the description of the Script Manager in Inside 

Macintosh, Volume V. If the language specified is not supported, this routine returns 

tmNoErr, but outputPtr iS NIL. 


TMEnglishToIntl 


Translating from English 


Function 

TMEnglishToIntl conveits an American English configuration string, which is 
pointed to by inputptr, to a configuration string pointed to by outputPtr. 

TMEnglishToIntl(hTerm: TermHandle; inputPtr: Ptr; VAR 
outputPtr: Ptr; language: INTEGER): OSErr; 

Description 

The function returns an operating-system error code if any internal errors occur. 

The terminal tool allocates space for outputPtr. Your application is responsible for 
disposing of the pointer with oisposPtr when done with it. 

language specifies the language to which the string is to be converted. Valid values 
for this field are shown in the description of the Script Manager in Inside Macintosh, 
Volume V. If the language specified is not supported, tmNoErr is still returned, but 
outputPtr is NIL. 
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Miscellaneous routines 

The routines described in this section perform a variety of tasks. 

TMGetToolName 

Getting the name of a tool 

TMGetToolName retums in name the name of the tool Specified by procio. 

Procedure TMGetToolName(procIO: INTEGER; VAR name: Str255); 

Description If procio references a terminal tool that does not exist, the Terminal Manager sets 

name to an empty string. 


TMSetRefCon 

Setting the terminal tool’s reference constant 

TMSetRefCon sets the terminal record’s refcon to the specified value. It is very 
important that your application use this routine to change the value of the reference 
constant, instead of changing it directly. 


Procedure TMSetRefCon(hTerm: TermHandle; refCon: LONGINT); 


TMGetRefCon 

Getting the terminal tool’s reference constant 

TMGetRefCon rctums the terminal record’s reference constant. 
Function TMGetRefCon(hTerm: TermHandle): LONGINT; 
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TMSetUserData 


Setting the userData field 

TMSetUserData sets the terminal record’s userData field to the value specified by 
userData. It is very important that your application use this routine to change the value 
of the userData field, instead of changing it directly. 

Procedure TMSetUserData(hTerm: TermHandle; userData: LONGINT); 


TMGetUserData 

Getting the userData field 

TMGetuserData returns the terminal record’s userData field. 

Function TMGetuserData(hTerm: TermHandle): LONGINT; 

TMGetVersion 

Getting 'vers' resource information 

TMGetVersion retums a handle to a relocatable block that contains the information 
that is in the terminal tool’s • vers ' resource with ID=1. Your application is responsible 
for disposing of the handle when done with it. 

♦ Note: The handle returned is not a resource handle. 

Function TMGetVersion(hTerm: TermHandle): Handle; 


TMGetTMVersion 

Getting the Terminal Manager version number 

TMGetTMVersion retums the version number of the Terminal Manager. 
Function TMGetTMVersion: INTEGER; 

Description The version number of the Terminal Manager described in this document is: 

CONST 

curTMVersion = 1; 
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TMGetCursor 


Getting the current cursor position 

TMGetCursor rctums the cuiTent position of the cursor. Numbering of rows and 


Function 

columns begins with 1. 

TMGetCursor(hTerm: TermHandle; cursType: TMCursorTypes): Point; 

Description 

Valid values for cursType are as follows: 

CONST 

cursorText = 1; 

cursorGraphics = 2; 

TYPE 

TMCursorTypes = INTEGER; 

For cursorText , the position returned is in row/column format, and for 
cursorGraphics the position is in pixel coordinates. 

TMDoTermKey 



Emulating a special terminal key 

TMDoTermKey emulates a special terminal key specified by theKey. 


Function 

TMDoTermKey(hTerm: TermHandle; theKey; Str255): BOOLEAN; 

Description 

If the terminal tool does not understand the key specified by theKey, this routine 
returns false. Otherwise, if the key specified is processed, this routine returns true. 

For information about the terminal keys supported by a terminal tool, refer to that 
tool’s documentation. 

This example shows how an application can use TMDoTermKey to emulate the user’s 
pressing a PFl key: 

IF TMDoTermKey(hTerm, 'PFl') THEN 

BEGIN 

END; 
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TMCountTe 2 nnKeys 


Counting special terminal keys 



TMCountTermKeys returns the number of special terminal keys that the terminal tool 
supports. 

Function 

TMCountTermKeys(hTerm): INTEGER; 

Description 

TMCountTermKeys returns 0 if the terminal tool supports no special terminal keys. 


TMGet IndTe ritiKey 


Getting a terminal key 



TMGetindTermKey retums the name of a specified key. 

Procedure 

TMGetIndTermKey(hTerm:TermHandle; id:INTEGER; VAR 
theKey:Str255) ; 

Description 

TMGetindTermKey returns in theKey the terminal key specified by id. If id 
specifies a key that does not exist, this routine retums an empty string. 


TMGet Te rmEnvirons 


Getting general terminal tool information 



TMGetTermEnvirons returns theEnvirons, which reflects the internal conditions 
of the terminal tool. The caller of this routine must fill in the version field of 
theEnvirons before calling TMGetTermEnvirons. 

Function 

TMGetTermEnvirons(hTerm; TermHandle; VAR theEnvirons: 

TermEnvironRec): TMErr; 

Description 

This routine returns tmNoErr, envversTooBig, or an operating-systerm error code. 
The fields in theEnvirons are as follows: 

TYPE 

TermEnvironPtr = ^TermEnvironRec; 

TermEnvironRec = RECORD 

version : INTEGER; 

termType : TMTermTypes; 

textRows : INTEGER; 

textCols : INTEGER; 

cellSize : Point; 

graphicSize : Rect; 

slop : Point; 

auxSpace ; Rect; 

END; 
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version is the version number of the requested terminal environment record, 
which is curTermEnvRecvers in this release of the Terminal Manager. The caller of 
the routine must fill in this field before calling TMCetTermEnvirons. 

termType is the type of terminal. termType can contain one or both of the 
following values: 

CONST 

tmTextTerminal = $0001; 

tmGraphicsTerminal = $0002; 

curTermEnvRecVers = 0; 

TYPE 

TMTermTypes = INTEGER; 

textRows is the number of rows in the terminal emulation region. The first row is row 
number 1. 

textcois is the number of columns in the terminal emulation region. The first column 
is column number 1. 

ceiisize is the height and width of each cell. 

graphicsize is the size of default rectangle of the graphics terminal tool measured in 
pixels. 

slop is the border of the terminal emulation region. 

auxspace is a rectangle that specifies any additional space that is required at the top, 
bottom, right, or left of the terminal emulation region, as shown in Figure 4-7 


■ Figure 4-7 Additional space in the terminal emulation region 


slop.V 


auxSpace.top 



.auxSpace.right 
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Routines that must be in your application 

Terminal tools do not provide all the code necessary to perform terminal emulations; your 
application must also provide some code (or at least pointers to code provided by other managers). 
This section describes the routines that must be in your application, which give the terminal tool 
important information about 

■ how to send data on the connection 

■ what to do with lines that scroll out of the terminal emulation region 

■ what to do when a specified string is found in the terminal emulation buffer 

■ what to do when the user wants to effect a break on the terminal 

■ what to do when the user is dragging the mouse in the terminal emulation region 

■ what the connection environment is like 


sendProc _ 

Sending data out along the connection 

when a tool needs to send data to another entity, it looks to your application to provide 
sendProc. sendProc may Simply be the routine that the Connection Manager uses to 
send data (as is the case in the next example), or it can be a routine that you have written. 

Function sendProc (thePtr: Ptr; theSize: LONGINT; refCon: LONGINT; 

flags: CMFlags): LONGINT; 

Description thePtr is a pointer to the data to be sent. 

thesize is the number of characters to be sent. 

ref Con is the reference constant field for sending terminal’s terminal. 

sendProc retums the actual number of characters sent. 

flags indicates whether or not the connection tool should send an end-of-message 
indicator. An end-of-message indicator needs to be supported by the particular 
communications protocol being used; if an end-of-message indicator is not supported by 
the connection protocol, your application should ignore this field. 
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Sample routine for sending data 

FUNCTION sendProc(thePtr: Ptr;theSize: LONGINT; 

refcon: LONGINT;flags: INTEGER): LONGINT; 

VAR 

theErr : CMErr; { Any errors } 


BEGIN 

sendProc := 0; { Assume the worst } 

IF gConn <> NIL THEN BEGIN 


{ DO NOT check to see if the conn is first open before sending } 

{ as the tool might be directly interpreting the data } 

{ Send the data } 

theErr :* CMWrite(gConn,thePtr,theSize,cmData,FALSE,NIL,0,flags); 


IF (theErr = noErr) THEN 
sendProc := theSize 

ELSE 

/ 

END; { Good Connection } 


{ If ok, we sent all } 
Handle errors } 


END; { sendProc } 


breakProc 

Sending a break 

Your application needs to contain information about how to send a break on a 
connection. Although it can contain the code that performs the break operation, your 
application can also point to a connection tool routine that performs the break. This 
section gives an example. 

Procedure breakProc(duration: LONGINT; refCon: LONGINT); 

Description duration specifies, in ticks, how long the break should last. 

ref Con is the reference constant field of the terminal record. 

Sample showing how to break a connection 

PROCEDURE breakProc(duration: LONGINT; refcon : LONGINT); 

BEGIN 

{ Here we choose to issue a synchronous break } 

IF gConn <> NIL THEN 

CMBreak(gConn, duration, FALSE, NIL); 

END; { breakProc } 
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cacheProc 


Caching lines from the terminal region 

Your application can cache lines that scroll off the top of the terminal emulation region 
and, if desired, display them in the terminal emulation window. If you want your 
application to display these lines, you have to provide the necessary code. If you do not 
want your application to display these lines, then your application should specify nil 
for cacheProc when it calls TMNew. 


Function 

Description 


cacheProc(refCon: LONGINT; theTermData:TermDataBlock): LONGINT; 

cacheProc must retum tmNoErr if no error Occurred during processing. Otherwise, 
it should retum an appropriate error code. 

ref Con is the reference constant for the terminal record. 

theTermData is a data Stmcture of type TermOataBlock: 


TYPE 

TermDataBlockH 

TermDataBlockPtr 

TermDataBlock 

flags 

theData 

auxData 

reserved 


'"TermDataPtr; 
'^TermDataBlock; 
RECORD 
TMTermTypes; 
Handle; 

Handle; 

LONGINT; 


END; 

theTerm. theData is a handle to a block on the heap. Your application can 
calculate the size of this block with GetHandieSize. Your application must copy 
any data it needs because theTermData belongs to the terminal tool and may not 
exist after cacheProc has completed. Your application can use HandToHand to 
copy the data. 


Sample showing how to cache lines 

FUNCTION cacheProc (refcon : LONGINT; theTermData : TermDataBlock ) : LONGINT; 

VAR 

sizeCached : LONGINT; 


BEGIN 

{ Check for data integrity } 

IF (theTermData.theData = NIL) THEN BEGIN 
cacheProc := -1; 

EXIT(cacheProc); 

END; { Bad Data } 

{ Cache either graphics or text } 

HLock(theTermData.theData) ; 

{ Get rid of the old cached data } 
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IF (gCache <> NIL) THEN 

DisposHandle(gCache); 

{ make a copy of new text } 
gCache := theTermData.theData; 

IF (HandToHand (gCache) <> noErr) THEN BEGIN 

gCache := NIL; (* Handle errors *) 

sizeCached := -1; 

END 

ELSE 

sizeCached := GetHandleSize(gCache); 

HUnlock(theTermData.theData)/ 

IF (theTermData.flags = tmGraphicsTerminal) THEN BEGIN 

{ theTermData.theData is a handle to a QD Picture } 
(* 

Could save it as PICT 
*) 

END { cache graphics } 

ELSE IF (theTermData.flags = tmTextTerminal) THEN BEGIN 
{ theTermData.theData is a handle to text } 

(* 

Could write it out to the data fork 
*) 

END; { cache text } 

END; { cacheProc } 


callBack 

Responding to a matched search parameter 

Your application can selectively filter data in the terminal emulation buffer by making use 
of a search call-back procedure. Since a tool will automatically call caiiBack when it 
finds a match to the search string, your appliation can respond in any way that you want 
it to. 

Procedure callBack(hTerm: TermHandle; refNum: INTEGER; foundRect: Rect); 

Description refNum is the reference number associated with a particular search. Reference numbers 

are assigned by the Terminal Manager when a search is added to a terminal record with the 
TMAddSearch routine. 

foundRect describes in row/column format where the match was found, with row 
and column numbers starting at 1. 
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clikLoop 


Responding to mouse clicks 

This routine is called when the user is dragging the mouse in the terminal emulation 
window. Initially, your application should process a mouse-down event by calling 
TMCiick, which in turn calls this routine. 

Function clikLoop(refCon: LONGINT): BOOLEAN; 

Description This routine returns true when the mouse is clicked within the cache region. 

Otherwise, it returns false. 


environsProc 

Getting connection environment information 

To get information about the connection environment, the terminal tool calls a routine in 
your application, environsProc. 

Function environsProc(refCon: LONGINT; VAR theEnvirons: ConnEnvironRec): 

CMErr; 

Description refCon is the reference constant for the terminal tool. 

theEnvirons is a data Structure containing the connection-environment record. Your 
application can either construct theEnvirons or use the Connection Manager routine 
CMGetConnEnvirons. For more information about theEnvirons, See 
“CMGetConnEnvirons” in Chapter 3. 

The example that follows shows how environsProc can point to a Connection 
Manager routine to retrieve information about the connection environment. 

Sample terminal environment routine 

FUNCTION environsProc(refCon: LONGINT;VAR theEnvirons: ConnEnvironRec): OSErr; 
BEGIN 

environsProc:= envNotPresent; { pessimism } 

theEnvirons.version := curConnEnvRecVers; { fill in version field ) 

IF (gConn <> NIL) THEN { Tool sets the version } 

environsProc:- CMGetConnEnvirons(gConn,theEnvirons); 

END; { environsProc } 
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Quick reference 

This section provides a reference to Terminal Manager routines and data structures. At the end of 
this section is a listing of routine selectors for programming in assembly language. 

Routines 

Terminal Manager routines See page 

InitTMrTMErr; 88 

TMActivate(hTerm: TermHandle; activate: BOOLEAN); 105 

TMAddSearch(hTerm: TermHandle; theString: Str255; 102 

where: Rect; searchType: TMSearchTypes; callBack: 

ProcPtr): INTEGER; 

TMChoose(VAR hTerm: TermHandle; where: Point; 92 

idleProc: ProcPtr): INTEGER; 

TMClear(hTerm: TermHandle); 100 

TMClearSearch(hTerm: TermHandle); 103 

TMClick(hTerm: TermHandle; theEvent: EventRecord); 106 

TMCountTermKeys(hTerm): INTEGER; 112 

TMDefault(VAR theConfig: Ptr; procID: INTEGER; 91 

allocate: BOOLEAN); 

TMDispose(hTerm: TermHandle); 101 

TMDoTermKey(hTerm: TermHandle; theKey: Str255): 111 

BOOLEAN; 

TMEnglishToIntl(hTerm: TermHandle; inputPtr: Ptr; VAR 108 

outputPtr: Ptr; language: INTEGER): OSErr; 

TMEvent(hTerm: TermHandle; theEvent: EventRecord); 107 

TMGetConfig(hTerm: TermHandle): Ptr; 98 

TMGetCursor(hTerm: TermHandle; cursType: 111 

TMCursorTypes): Point; 

TMGetIndTermKey(hTerm:TermHandle; id:INTEGER; VAR 112 

theKey:Str255); 

TMGetLine(hTerm: TermHandle; lineNo: INTEGER; VAR 100 

theTermData:TermDataBlock); 

TMGetProcID(name: Str255): INTEGER; 88 

TMGetRefCon(hTerm: TermHandle): LONGINT; 109 

TMGetSelect(hTerm: TermHandle; theData: Handle; VAR 104 

theType: ResType): LONGINT; 
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Terminal Manager routines 


See page 


TMGetTermEnvirons (hTeriti: TermHandle; VAR theEnvirons: 112 

TerraEnvironRec) : TMErr; 

TMGetToolName(procID: INTEGER; VAR name: Str255); 109 

TMGetTMVersion: INTEGER; HO 

TMGetUserData(hTerm: TermHandle): LONGINT; HO 

TMGetVersion(hTerm: TermHandle): Handle; HO 

TMIdle(hTerm: TermHandle); 99 

TMIntlToEnglish(hTerm: TermHandle; inputPtr: Ptr; VAR 108 

outputPtr: Ptr; language: INTEGER): OSErr; 

TMKey(hTerm: TermHandle; theEvent: EventRecord); 106 

TMMenu(hTerm: TermHandle; menuID: INTEGER; item: 105 

INTEGER): BOOLEAN; 

TMNew(termRect: Rect; viewRect: Rect; flags: TMFlags; 89 

procID: INTEGER; owner: WindowPtr; sendProc: ProcPtr; 
cacheProc: ProcPtr; breakProc: ProcPtr; clikLoop: 

ProcPtr; environsProc: ProcPtr; refCon: LONGINT; 
userData: LONGINT): TermHandle; 

TMPaint(hTerm: TermHandle; theTermData:TermDataBlock; 99 

theRect: Rect); 

TMRemoveSearch(hTerm: TermHandle; refNum: INTEGER); 103 

TMReset(hTerm: TermHandle); 101 

TMResize(hTerm: TermHandle; newTermRect: Rect); 101 

TMResume(hTerm: TermHandle; resume: BOOLEAN); 105 

TMScroll(hTerm: TermHandle; dH, dV: INTEGER); 100 

TMSetConfig(hTerm: TermHandle; thePtr: Ptr): INTEGER; 98 

TMSetRefCon(hTerm: TermHandle; refCon: LONGINT); 109 

TMSetSelection(hTerm: TermHandle; theSelection: 104 

TMSelection; selType: TMSelTypes); 

TMSetupCleanup(procID: INTEGER; theConfig: Ptr; 96 

count: INTEGER; theDialog: DialogPtr; VAR 
magicCookie: LONGINT); 

TMSetupFilter(procID: INTEGER; theConfig: Ptr; count: 95 

INTEGER; theDialog: DialogPtr; VAR theEvent: 

EventRecord; VAR theltem: INTEGER; VAR magicCookie: 

LONGINT): BOOLEAN; 

TMSetupItem(procID: INTEGER; theConfig: Ptr; count: 96 

INTEGER; theDialog: DialogPtr; VAR theltem: INTEGER; 

VAR magicCookie: LONGINT); 
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Terminal Manager routines See page 

TMSetupPostflight(procID:INTEGER); P7 

TMSetupPreflight(procID: INTEGER; VAR magicCookie: 94 

LONGINT): Handle; 

TMSetupSetup(procID: INTEGER; theConfig: Ptr; count: 95 

INTEGER; theDialog: DialogPtr; VAR magicCookie: 

LONGINT); 

TMSetUserData(hTerm: TermHandle; userData: LONGINT); 110 

TMStream(hTerm: TermHandle; theBuffer: Ptr; 99 

theLength: LONGINT; flags: CMFlags): LONGINT; 

TMUpdate(hTerm: TermHandle; visRgn: RgnHandle); 106 

TMValidate(hTerm: TermHandle): BOOLEAN; 91 


Routines in your application 


See page 


sendProc (thePtr: Ptr; theSize: LONGINT; refCon: 
LONGINT; flags: CMFlags): LONGINT; 

breakProc(duration: LONGINT; refCon: LONGINT); 

cacheProc(refCon: LONGINT; 
theTermData:TermDataBlock): LONGINT; 

callBack(hTerm: TermHandle; refNum: INTEGER; 
foundRect: Rect); 

clikLoop(refCon; LONGINT): BOOLEAN; 

environsProc(refCon: LONGINT; VAR theEnvirons: 
ConnEnvironRec): CMErr; 

Terminal record 

TYPE 

TermHandle 
TermPointer 
TermRecord 

procID 

flags 
errCode 

refCon 
userData 

defProc 

config 
oldConfig 


'^TermPointer; 

^TermRecord; 

RECORD 

INTEGER 

TMFlags; 

TMErr; 

LONGINT; 

LONGINT; 

ProcPtr; 

Ptr; 

Ptr; 


114 

115 

116 

117 

118 
118 


Chapter 4: Terminal Manager 121 







environsProc 

reservedl 

reserved2 


ProcPtr; 
LONGINT; 
LONGINT; 


tmPrivate 


Ptr; 


END; 


sendProc : 

ProcPtr; 

breakProc : 

ProcPtr; 

cacheProc : 

ProcPtr; 

clikLoop : 

ProcPtr; 


owner 


WindowPtr; 

termRect 


Rect; 

viewRect 


Rect; 

visRect 


Rect; 

lastidle 

: 

LONGINT; 

selection 

; 

TMSelection 

selType 

5 

TMSelTypes; 

mluField 

. 

LONGINT; 


Constants and data types 

TYPE 

TMSelection = 

CASE INTEGER OF 
1 : ( 

selRect : 

) / 

2 : ( 

selRgnHandle : 
filler : 

) ; 

END; 


RECORD 


Rect; 


RgnHandle; 

LONGINT; 


TYPE 

TermDataBlockH 

TermDataBlockPtr 

TermDataBlock 

flags 

theData 

auxData 

reserved 

END; 


^TermDataPtr; 
'"TermDataBlock; 
RECORD 
TMTermTypes; 
Handle; 

Handle; 

LONGINT; 
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TYPE 


TermEnvironPtr 

TermEnvironRec 

version 

termType 

textRows 

textCols 

cellSize 

graphicSize 

slop 

auxSpace 

END; 


TYPE 

TMErr 


TermEnvironRec; 
RECORD 
INTEGER; 
TMTermTypes; 
INTEGER; 

INTEGER; 

Point; 

Rect ; 

Point; 

Rect; 


OSErr; 


CONST 

tmGenericError = -l; 

tmNoErr = 0; 

tmNotSupported = 7; 

tmNoTools = 8; 


CONST 

curTermEnvRecVers = 0; 

curTMVersion = 1 ; 


{ 


bit masks for flags field 
tminvisible 
tmSaveBef oreClear *= 

tmNoMenus = 

tmAutoScroll = 


of terminal record 
$ 00000001 ; 
$ 00000002 ; 
$00000004; 
$00000008; 


} 


{ selection types } 

selTextNormal = $0001; 
selTextBoxed = $0002; 
selGraphicsMarquee = $0004; 
selGraphicsLasso = $0008; 


{ search modifiers } 

searchNoDiacrit = $0100; 

searchNoCase = $0200; 


Chapter 4; Terminal Manager 123 






TYPE 

TMSearchTypes = INTEGER; 


I tarriiinal typ©s in T©irinEnvir'onR©c data stjructur© } 


CONST 

tmT©xtT©rminal 

$0001; 

tmGraphicsT©rminal = 

$0002; 


{ TMChoos© r©turn valu©s } 


choos©Disast©r =* ”2; 

choos©Fail©d = ”1; 

choos©OKMinor = 1; 

choos©OKMajor = 2; 

choos©Canc©l = 3; 


Terminal Man^^er routine selectors 

♦ Assembly note: The Communications Toolbox routines are accessed via a Macintosh 

Operating System trap, ao contains a pointer to the routine parameters. You can call each 
of the Communications Tooolbox routines with a macro that has the same name as the 
routine preceded by an underscore. When expanded, these macros put the routine selector 
onto the stack, set ao to point to the selector, invoke the trap macro _comTooiTrap 
($A08B), and finally pop the routine selector back off the stack. It is your application’s 
responsibility to remove the parameters. 


InitTM 

.EQU 

769 

TMEnglishToIntl 

.EQU 

798 

TMActivat© 

.EQU 

775 

TMEv©nt 

.EQU 

813 

TMAddS©arch 

.EQU 

807 

TMG©tConfig 

.EQU 

795 

TMChoos© 

.EQU 

812 

TMG©tCursor 

.EQU 

810 

TMCl©ar 

.EQU 

781 

TMG©tIndT©rmK©y 

.EQU 

816 

TMCl©arS©arch 

.EQU 

809 

TMG©tLin© 

.EQU 

784 

TMClick 

.EQU 

111 

TMG©tProcID 

.EQU 

799 

TMCountT©rmK©ys 

.EQU 

815 

TMG©tR©fCon 

.EQU 

802 

TMD©fault 

.EQU 

789 

TMG©tS©l©ct 

.EQU 

783 

TMDispos© 

.EQU 

111 

TMG©tT©rmEnvirons 

.EQU 

811 

TMDoT©rmK©y 

.EQU 

814 

TMG©tTMV©rsion 

.EQU 

806 
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TMGetToolName .EQU 
TMGetUserData .EQU 
TMGetVersion .EQU 
TMIdle .EQU 
TMIntlToEnglish .EQU 
TMKey .EQU 
TMMenu .EQU 
TMNew .EQU 
TMPaint .EQU 
TMRemoveSearch .EQU 
TMReset .EQU 
TMResize .EQU 
TMResume .EQU 
TMScroll .EQU 




TMSetConfig 

.EQU 

796 

TMSetRefCon 

.EQU 

801 

TMSetSelection 

.EQU 

785 

TMSetupCleanup 

.EQU 

794 

TMSetupFilter 

.EQU 

792 

TMSetupItem 

.EQU 

793 

TMSetupPostflight 

.EQU 

817 

TMSetupPreflight 

.EQU 

790 

TMSetupSetup 

.EQU 

791 

TMSetUserData 

.EQU 

803 

TMStream 

.EQU 

778 

TMUpdate 

.EQU 

773 

TMValidate 

.EQU 

788 


800 

804 

805 

787 

797 

772 

779 

770 

774 

808 

780 

782 

776 

786 
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Chapter 5 File Transfer Manager 



























































































THIS CHAPTER describes the File Transfer Manager, the 
Communications Toolbox manager that allows applications to implement file 
transfer services without having to take into account underlying file transfer 
protocols. This chapter describes fundamental concepts about the File Transfer 
Manager. Then it describes the file transfer record, which is the most 
impKDitant record of the File Transfer Manager. Next, this chapter presents a 
detailed description of each routine provided by the File Transfer Manager. At 
the end of the chapter, you’ll find a “Quick Reference” to routines, data 
structures, and routine selectors for programming in assembly language. 

In this chapter, the term your application refers to the application you are 
writing for the Macintosh, which will implement communications services 
for users. Be careful not to confuse the services your application provides 
with the services that tools provide. 

To use the File Transfer Manager, you need to be familiar with 

■ the Resource Manager (described in Inside Macintosh, Volumes I, IV, V) 

■ the File Manager (described in Inside Macintosh, Volumes II, IV, V) 

■ the Standard File Package (described in Inside Macintosh, Volumes I, IV) 

■ the Connection Manager (described in Chapter 3 of this document) 
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About the File Transfer Manager 

By using File Transfer Manager routines, your application can send files to or receive files from 
another entity without having to take into account underlying file transfer protocols. File 
transfer tools, which are discussed in Chapter 11, are responsible for implementing file transfer 
services according to specific protocols. 

The File Transfer Manager provides generic file transfer services for a transfer between your 
application and another computer process. The other process can be running on the same computer 
as your application, or on any other type of computer. 

Here’s what happens inside the File Transfer Manager. An application makes a request of the 
File Transfer Manager when it needs it to send a file or perform some other file transfer function. 
The File Transfer Manager then sends this request to one of the tools that it manages. The tool 
provides the service according to the specifics of its file transfer protocol. Once the tool has 
finished, it passes back to the application any relevant parameters and return codes. 

Figure 5-1 shows the data flow into and out of the File Transfer Manager. 

■ Figure 5-1 Data flow into and out of the File Transfer Manager 



The most important data structure maintained by the File Transfer Manager is the file transfer 
record, which contains all the specifics about a file transfer. For example, the file transfer record 
might show that the File Transfer Manager should use the XMODEM tool to perform file transfers, 
and that the tool should not display any custom menus while transferring files. 
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One important aspect of the file transfer record is that it allows you to use protocol- 
independent routines. Protocol-independent routines allow applications to use File Transfer 
Manager services without regard for the underlying file transfer protocols. In other words, when an 
application wants to transfer a file from a remote entity, it tells the File Transfer Manager to get 
the file, and the File Transfer Manager figures out exactly how to implement the transfer for a 
specific protocol. 

Another important feature of the file transfer record is that it lets you use multiple instances 
of the same tool. The same tool can be used by different processes at the same time, as in a 
MiltiFinder environment, or by differeent threads in a given application. 

The file transfer record is described in greater detail later in this chapter. 

Besides providing basic file transfer routines, the File Transfer Manager includes routines that 
help your application configure a file transfer tool, either by presenting the user with a dialog box or 
by interfacing directly with a scripting language. The File Transfer Manager also contains routines 
that can help you localize your applications in other languages. 

You can write applications that use the File Transfer Manager with other Communications 
Toolbox managers to create a communications application with basic connection, terminal 
emulation, and file transfer capabilities. Or, you can use the File Transfer Manager with some other 
connection service and terminal emulation service. You can also write your own file transfer tool for 
the File Transfer Manager to use. (This procedure is discussed in Chapters 8 and 11.) Regardless of 
which you choose, your application needs to be able to handle different file transfer tools so that 
users can change tools and still be able to use your program. 


The file transfer record 

The file transfer record contains information needed by your application and the file transfer tool to 
send files, such as whether to send data or receive data, and where to find the routines that 
perform the actual sending and receiving of files. The file transfer record also contains pointers to 
File Transfer Manager internal data structures. Most of the fields in the file transfer record are filled 
in when an application calls ftncw, described later in this chapter. 

Because the context for a given file transfer is maintained in a file transfer record, an application 
can perform several file transfers simultaneously (using one or more file transfer tools), by creating 
a separate file transfer record for each transfer. For details, see “FTNew: Creating a File Transfer 
Record,” later in this chapter. 

A Important Your application, in order to be compatible with future releases of the File 
Transfer Manager, should not directly manipulate the fields of the file 
transfer record (with the exception of config and oidconf ig). The 
File Transfer Manager provides routines that applications and tools can use 
to change the fields in the file transfer record. These routines are discussed 
later in this chapter, a 
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File transfer record data structure 


TYPE 


FTHandle 

= 

'"FTPtr; 

FTPtr 

as 

'"FTRecord; 

FTRecord 

= 

PACKED RECORD 

procID 

: 

INTEGER; 

flags 

. 

FTFlags; 

errCode 


FTErr; 

refCon 

J 

LONGINT; 

userData 

: 

LONGINT; 

defProc 


ProcPtr; 

config 

; 

Ptr; 

oldConfig 

: 

Ptr; 

environsProc 


ProcPtr; 

reservedl 


LONGINT; 

reserved2 


LONGINT; 

ftPrivate 


Ptr; 

sendProc 


ProcPtr; 

recvProc 


ProcPtr; 

writeProc 


ProcPtr; 

readProc 


ProcPtr; 

owner 


WindowPtr; 

direction i 


FTDirection; 

theReply : 


SFReply; 

writePtr 


LONGINT; 

readPtr 


LONGINT; 

theBuf 


'"char; 

bufSize 


LONGINT; 

autoRec 


Str255; 

attributes 

:nd; 


FTAttributes; 
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procID 

prociD is the file transfer tool ID. This value is dynamically assigned by the File Transfer Manager 
when your application calls FTGetProcio. 


flags 

flags is a bit field that your application can use to determine when a file transfer has completed, 
and if the file transfer was successful. Valid values are as follows: 


CONST 

ftIsFTMode 

ftNoMenus 

ftQuiet 

ftSucc 


$ 00000001 ; 

$ 00000002 ; 

$00000004; 

$00000080; 


TYPE 

FTFlags = LONGINT; 

ftisFTMode indicates whether or not a file transfer is in progress. A tool turns this bit on 
just prior to performing the actual file transfer, and turns it off when the file transfer stops. 

The file transfer tool will not display any custom menus if your application sets the 
ftNoMenus bit. The file transfer tool will not display any status dialog boxes or error alerts if your 
application sets the ftQuiet bit. If your application turns ftQuiet on, it is responsible for 
displaying status dialog boxes and error alerts that the tool would have displayed. Applications 
typically use these two bits to hide the file transfer tool from the user. 

ftsucc is a bit set by the file transfer tool when a file transfer completes successfully. 

Your application can first check to see if ftisFTMode toggles from on to off to find out 
when the file transfer has completed. Then, it can check ftsucc to see if the file transfer was 
completed successfully. 

The other bits of flags are reserved by Apple Computer 


errCode 

errcode contains the last error reported to the File Transfer Manager. If errCode is negative, 
an operating-system error occurred. If errCode is positive, a File Transfer Manager error occured. 
Valid values are as follows: 

CONST 

ftGenericError 
ftNoErr 
ftRejected 
ftFailed 
ftTimeOut 
ftTooManyRetry 
ftNotEnoughDspace 
ftRemoteCancel 
ftWrongFormat 
ftNoTools 
ftUserCancel 
ftNotSupported 
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TYPE 


FTErr = OSErr; 

refCon 

refcon is a four-byte field that your application can use. 

userData 

userData is a four-byte field that your application can use. 

defProc 

defproc isa pointer to the file transfer tool’s main definition procedure, which is contained in a 
code resource of type ' fdef •. 

config 

conf ig is a pointer to a data block that is private to the file transfer tool. It can contain 
information like retry and timeout values, but the contents vary from tool to tool. 

Your application can store the contents of conf ig to save the state of a file transfer in a 
document. The structure, size, and contents of the configuration record are set by the tool. Your 
application can determine the size of the configuration record by calling GetPtrsize, overwrite 
its contents using BiockMove, and validate the contents with FTVaiidate. 

Your application can use FTGetconfig and FTSetConfig to manipulate fields in this 
record. For details, read “Interfacing with a Scripting Language,” later in this chapter. 

You can find a description of config from a file transfer tools perspective in Chapter 8. 

oldConfig 

oidconf ig is a pointer to a data block that is private to the file transfer tool and contains the 
most recently saved version of config. Your application is responsible for setting oidconfig 
when the user saves a session document. 

environsProc 

environsProc is a pointer to a routine in your application that the file transfer tool calls to 
obtain a record describing the connection environment. For more information about 
environsProc, See “environsProc: Getting Connection Environment Information,” later in 
this chapter. 

reservedl and reserved2 

reservedi and reservedz are fields reserved for the File Transfer Manager. Your application 
must not use this field. 

ftPrivate 

ftPrivate is a pointer to a data block that is private to the file transfer tool. Your application 
must not use this field. 
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sendProc 

sendProc is a pointer to a routine that your application uses to send data. This routine is 
discussed under “sendProc: Sending Data, ” later in this chapter. 

recvProc 

recvProc is a pointer to a routine that your application uses to request data. This routine is 
discussed under “recvProc: Receiving Data,” later in this chapter. 

wribeProc 

writeProc is a pointer to a routine in your application that writes data to a file. If this field is 
NIL, the file transfer tool performs standard file operations (that is, writing to a disk). The file 
transfer tool checks this field to see if your application has a writeProc routine. If it does, the 
tool lets writeProc handle writing data. 

This routine an be used to perform postprocessing upon a file being received, and is discussed 
under “writeProc: Writing Data,” later in this chapter. 

readProc 

readProc is a pointer to a routine in your application that reads data from a file. If this field is 
NIL, the file transfer tool performs standard file operations (that is, reading data from a disk). The 
file transfer tool checks this field to see if your application has a readProc routine. If it does, 
the tool lets readProc handle reading data. 

This routine an be used to perform preprocessing upon a file being sent, and is discussed under 
“readProc: Reading Data,” later in this chapter. 

owner 

owner is a pointer to a window (or grafPort) relative to which the file transfer status dialog box is 
positioned. If this field is nil, the file transfer tool will not display a file transfer status dialog box. 

direction 

direction is a field that indiates whether a file is being sent to or received from another entity. 
Your appliation passes this field as a parameter to pTstart (described later in this chapter). Valid 
values in this field are as follows: 

CONST 

ftReceiving *0; 

ftTransmitting = 1; 

ftFullDuplex = 2; 

TYPE 

FTDirection = INTEGER; 
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theReply 

theRepiy is an sFRepiy data stmcture. The SFRepiy data structure should contain the 
reference number of the working directory of the default volume for files being sent or received. If 
a file is being sent, the data structure should also contain the name of the file to be sent. If a file is 
being received and your application has information about the filename (for example, from a 
scripting language), the data structure should contain the filename to be used. Otherwise, pass an 
empty string for theRepiy. filename. 

writePtr, readPtr, theBuf, and bufSize 

writePtr, readPtr, theBuf , and bufsize are properties of a particular file transfer tool. 

autoRec 

autoRec is a String that represents the start sequence a remote entity sends, causing the 
Macintosh to enter a file-reception mode. If this string is of length 0, remote-entity-initiated file 
transfers are not supported by the file transfer tool. It is the application’s responsibility to make 
use of this field by searching the data stream for this sequence of characters. The Connection 
Manager, described in Chapter 3, provides routines that your application can use to search an 
incoming data stream for a specified sequence of characters. 

attributes 


attributes is a field that describes the file transfer protocol supported by the file transfer tool. 


The bits 

in attributes are as follows: 


CONST 


ftSameCircuit 

= 

$0001; 


ftSendDisable 

= 

$0002; 


ftReceiveDisabie 

= 

$0004; 


ftTextOnly 


$0008; 

TYPE 


FTAttributes 

= 

INTEGER 


ftsamecircuit indicates whether the file transfer tool creates its own data connection or 
expects the application to provide the connection. If this bit is set, the file transfer tool uses the 
data connection provided by the application. This bit is set by the file transfer tool. 

ftsendDisabie indicates that the file transfer tool does not allow users to send files. Some 
tools that support sending files turn this bit on when they are in a mode that does not allow users 
to initiate sending files. When this bit is on, your application should dim any menu items that allow 
users to send files. 

ftReceiveDisabie indicates that the file transfer tool does not allow users to receive files. 
Some tools that support receiving files turn this bit on when they are in a mode that does not allow 
users to initiate receiving files. When this bit is on, your application should dim any menu items that 
allow users to receive files. 

ftTextoniy indicates that the file transfer tool sends and receives only text files (files of 
type text); the tool does not handle resource forks. The file transfer tool sets this bit. 

The other bits of this field are reserved by Apple Computer 
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File Transfer Manager routines 

The following sections describe the routines that tools and applications can use to access File Transfer 
Manager services. Your application can not call these routines from interrupt level. 

Below is a listing of the routines described in this section in the order in which they are presented. 


InitFT / 138 

FTAbort / 150 

FTGetProcID / 139 

FTDispose / 150 

FTNew / 139 

FTActivate / 151 

FTDefault / 141 

FTResume / 151 

FTValidate / I4l 

FTMenu / 152 

FTChoose / 142 

FTEvent / 152 

FTSetupPreFlight / 144 

FTIntlToEnglish / 153 

FTSetupSetup / 145 

FTEnglishToIntl / 153 

FTSetupFilter / 145 

FTGetToolName / 154 

FTSetupItem / 146 

FTSetRefCon / 154 

FTSetupCleanup / 146 

FTGetRefCon / 154 

FTSetupPostFlight / 147 

FTSetUserData / 155 

FTGetConfig / 148 

FTGetUserData / 155 

FTSetConfig / 148 

FTGetVersion / 155 

FTStart / 149 

FTGetFTVersion / 155 

FTExec / 150 
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Preparing for a file transfer 

Before your application can start a file transfer, it must initialize the File Transfer Manager (by 
calling initFT), find out the procio of the tool it requires (by calling FTCetProcio), create 
a file transfer record (by calling FTNew), and then configure the file transfer tool (by restoring 
conf ig from a saved document; or by calling FTChoose, the file transfer tool custom tool- 
settings routines, or FTSetConfig). 

InitFT 


Tnkiati7.ing the File Transfer Manager 

InitFT initializes the File Transfer Manager. Your application must call this routine after 
calling the standard Macintosh Toolbox initialization routines. 

A Warning Your application must initialize the Communications Resource Manager (by 



calling initcRM) and then the Communications Toolbox Utilities (by calling 
initCTButiiities), regardless of whether or not it uses any of their calls, before it 
initializes the File Transfer Manager, a 

Function 

InitFT: FTErr; 

Description 

InitFT returns an operating-system error code if appropriate. Valid values are; 

TYPE 

FTErr = OSErr; 

CONST 

ftGenericError = -1; 

ftNoErr = 0; 

ftNoTools = 8; 

Your application must check for the presence of the Communications Toolbox before 
calling this function. Sample code under “Determining Whether the Managers are Installed” 
in Appendix B shows you how your appliation can make this check. 
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FTGetProcID 


Getting current procio information 

Your application should call FTCetProcio just before creating a new file transfer 


Function 

record, to find out the prociD of a tool. 

FTGetProcID(name: Str255): INTEGER; 

Description 

name Specifies a file transfer tool. If there is a file transfer tool in the folder named 
Communications Folder with the specified name, this routine returns its prociD. If 
name refers to a nonexistent file transfer tool, this routine returns -1. 

FTNew 



Creating a file transfer record 


Function 

Before your application can transfer files, it must create a file transfer record. FTNew 
creates a new file transfer record, fills in the fields that it can, based upon the parameters 
that were passed to it; and returns a handle to the new record in FTHandie. FTNew 
automatically makes two calls to FTOefauit (described later in this chapter) to fill in 
conf ig and oidconf ig. The File Transfer Manager then loads the file transfer tool’s 
main definition procedure, moves it high in the current heap, and locks it. If an error 
occurs that prevents a new file transfer record from being created (for example, running 
out of memory), ftnbw passes back nil in FTHandie. 

FTNew(procID: INTEGER; flags: FTFlags; sendProc: ProcPtr; 
recvProc: ProcPtr; readProc: ProcPtr; writeProc: ProcPtr; 
environsProc: ProcPtr; owner: WindowPtr; refCon: LONGINT; 

userData: LONGINT): FTHandie; 

Description 

prociD specifies the file transfer tool the File Transfer Manager will use to transfer data. 

flags is a bit field with the following masks: 

CONST 

ftIsFTMode = $0001; 

ftNoMenus = $0002; 

ftQuiet = $0004; 

ftSucc = $0080; 

TYPE 

FTFlags = LONGINT; 

flags represents a request from your application for a level of service. Your 
application can set only two of these bits, ftNoMenus and ftQuiet. If your 
application sets ftNoMenus, the file transfer tool will not display any custom menus. If 
your application sets ftQuiet, the file transfer tool will not display any windows. 
Applications typically use these bits to hide the file transfer tool from the user. 
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Apple Computer has reserved the bits of flags that are not shown in this 
document. Do not use them, or your code may not work in the future. 

ftsucc is a bit that is set by the file transfer tool when a file transfer completes 
successfully. 

Your application can check to see if ftisFTMode toggles from on to off to find 
out when the file transfer has completed. Then it can check ftsucc to see if the file 
transfer was completed successfully. 

sendProc is a pointer to a routine that the application uses to send data. 

recvProc is a pointer to a routine that the application uses to request data. 

readProc is a pointer to a routine in your application that reads data from a file. The file 
transfer tool checks this field to see if your application has a readProc routine. If it 
does, the tool lets readProc handle reading data. If nil, the file transfer tool 
performs standard file operations (that is, reading data from a disk). 

This function can be used to perform preprocessing upon a file being sent, and is 
discussed later in this chapter, in “Routines Your Application Provides.” 

writeProc is a pointer to a routine in your application that writes data to a file. The file 
transfer tool checks this field to see if your application has a writeProc routine. If it 
does, the tool lets writeProc handle writing data. If nil, the file transfer tool 
performs standard file operations (that is, writing to a disk). 

This function can be used to perform post-processing upon a file being received, and 
is discussed later in this chapter, in “Routines Your Application Provides.” 

environsProc is a pointer to a routine that the file transfer tool can call when it wants 
to get information about the connection. See Chapter 3 for more information about the 
CMGetConnEnvirons routine. 

owner is a pointer to a window, relative to which the file transfer status dialog box is 
positioned. If this field is nil, the File Transfer Manager will not display a file transfer 
status dialog box. 

refcon and userData are fields that your application Can use. 
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FTDefault 


Initializing the file transfer record 


Procedure 

FTDefault fills the Specified configuration record with the default configuration 
specified by the file transfer tool, ftngw calls this procedure automatically when it fills 
in the conf ig and oidconfig fields in a new file transfer record. 

FTDefault(VAR theConfig; Ptr; procID: INTEGER; allocate: 

BOOLEAN); 

Description 

If allocate is TRUE, the tool allocates Space for theConfig in the Current heap 
zone. 


FTValidate 


Validating the file transfer record 

FTValidate performs an internal consistenqr check on the configuration and private 


Function 

data records of the file transfer record, ftncw and FTSetconfig call this routine 
after they have created a new file transfer record, to make sure that the the record 
contains values identical to those specified by the file transfer tool. 

FTValidate(hFT: FTHandle): BOOLEAN; 

Description 

If the validation fails, the File Transfer Manager returns true and the file transfer tool 
fills the configuration record with default values by calling FTDefault. 

Your application can call this routine after restoring a configuration, to verify that the 
file transfer record contains the correct information, in a manner similar to that shown 
next. 

BlockMove (saveConf ig^ hFT'^'". conf ig, GetPtrSize (hFT^'". conf ig) ) ; 

IF FTValidate (hFT) THEN BEGIN 
{ validate failed } 

END 

ELSE BEGIN 

{ validate succeeded } 

END 
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FTChoose 


Configuring a file transfer tool 

An appliation can configure a file transfer tool in one of three ways. The easiest and most 
straightforward way is by calling the FTChoose routine. This routine presents the user 
with a dialog box similar to the one shown in Figure 5-2. 

m Figure 5-2 The standard tool-settings dialog box 



This area is 
filled in by the 
file-transfer tool. 


The second way an application can configure a file transfer tool is by presenting the 
user with a custom tool-settings dialog box. This method is much more difficult and 
involves calling six routines. The routines are described in the next section, “Custom 
Configuration of a File Transfer Tool,” and “The Custom Tool-Settings Dialog Box” in 
Appendix B provides example code. 

The third way your application can configure a file transfer tool is by using the 
scripting language interface, described under “Interfacing with a Scripting Language,” later 
in this chapter. This method allows your application to bypass user interface elements. 

Function FTChoose(VAR hFt:FTHandle; where: Point; idleProc: ProcPtr): 

INTEGER; 

Description where is the point, specified in global coordinates, where the upper-left comer of the 

dialog box should appear. It is recommended that your application place the dialog box as 
close as possible to the upper-left comer of the screen, because the size of the dialog box 
varies from tool to tool. 

idleProc is a procedure with no parameters that the File Transfer Manager will 
automatically call every time FTChoose loops through the setup dialog filter procedure. 
Pass NIL if your application has no idieproc. 
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FTSetupSetup 


Setting up tool-settings dialog box items 

FTSetupSetup tells the file transfer tool to set up controls (like radio buttons or check 


Procedure 

boxes) in the dialog item list returned by FTSetupPrefiight. 

FTSetupSetup(procID: INTEGER; theConfig: Ptr; count: INTEGER; 
theDialog: DialogPtr; VAR magicCookie: LONGINT); 

Description 

prociD is the ID for the file transfer tool being configured. Your application should use 
the same value for procio as it passed to FTSetupPreflight. 

theConfig is a pointer to a configuration record for the tool being configured. 

count is the number of the first item in the dialog item list appended to the dialog box. 

theDialog is the dialog box in which configuration is taking place. 
magicCookie is a pointer to private storage for the file transfer tool. 


FTSetupFilter 


Filtering tool-settings dialog box events 


Function 

Your application calls FTSetupFiiter as a filter procedure before it calls the standard 
modal dialog box filter procedure for the tool-settings dialog box. This routine allows file 
transfer tools to filter events in the tool-settings dialog box. 

FTSetupFilter(prociD: INTEGER; theConfig: Ptr; count:INTEGER; 

theDialog: DialogPtr; VAR theEvent: EventRecord; VAR theltem: 
INTEGER; VAR magicCookie: LONGINT): BOOLEAN; 

Description 

If the event passed-in was handled, FTSetupFilter returns true, false 
indicates that your application should perform standard dialog box filtering. 

prociD is the ID for the file transfer tool that is being configured. Your application 
should use the same value for prociD as it passed to FTSetupPreflight. 

theConfig is the pointer to the configuration record for the tool being configured. 

count is the number of the first item in the dialog item list appended to the dialog box. 

theDialog is the dialog box performing the configuration. 

theEvent is the event record for which filtering is to take place. 

theltem Can retum the item clicked in the dialog box. 

magicCookie is a pointer to private storage for the file transfer tool. 
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FTSetupItem 


Processing tool-settings dialog box events 

FTSetupItem processes events for controls in the custom tool-settings dialog box. 


Procedure 

FTSetupItem(procID: INTEGER; theConfig: Ptr; count: INTEGER; 
theDialog: DialogPtr; VAR theltem: INTEGER; VAR magicCookie: 
LONGINT); 

Description 

prociD is the ID for the file transfer tool being configured. Your application should use 
the same value for procio as it passed to FTSetupPreflight. 

theConfig is a pointer to the configuration record for the tool being configured. 

count is the number of the first item in the dialog item list appended to the dialog box. 

theDialog is the dialog box performing the configuration. 

theltem is the item clicked in the dialog box. This value can be modified and sent back. 

magicCookie is a pointer to private storage for the file transfer tool. 


FTSetupCleanup 


Performing clean-up operations 

FTSetupCleanup disposes of any storage allocated in FTSetupPref light and 


Procedure 

performs other clean-up operations. 

FTSetupCleanup(prociD: INTEGER; theConfig: Ptr; count: INTEGER; 
theDialog: DialogPtr; VAR magicCookie: LONGINT); 

Description 

prociD is the ID for the file transfer tool that is being configured. Your application 
should use the same value for prociD as it passed to FTSetupPref light. 

theConfig is the pointer to the configuration record for the tool being configured. 

count is the number of the first item in the dialog item list appended to the dialog box. 

theDialog is the dialog box performing the configuration. 

magicCookie is a pointer to private storage for the file transfer tool. 
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FTSetupPostflight 


Closing the tool file 

FTSetupPostfiight closes the tool file if it is not being used by any session. 
Procedure FTSetupPostfiight(procID:INTEGER); 

Description prociD is the ID for the file transfer tool that is being configured. Your application 

should use the same value for prociD as it passed to FTSetupPreflight. 
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Interfacing with a scripting language 

Your application does not have to rely on users making selections from dialog boxes in order to configure a file 
transfer tool. FTGetconfig and FTSetConfig provide the services that your application needs to 
interface with a scripting language. 

FTGetconfig 


Getting the configuration string 

FTGetconfig gets a Configuration string from the file transfer tool. 


Function 

FTGetconfig(hFT: FTHandle): Ptr; 

Description 

FTGetconfig retums a null-terminated, C-style string from the file transfer tool 
containing tokens that fully describe the configuration of the file transfer record. For an 
example, see the description of the next routine. If an an error occurs, FTGetconfig 
returns nil. 

It is the responsibility of your application to dispose of ptr. 

FTSetConfig 



Setting the configuration with a string 

FTSetConfig passes a Configuration string to the file transfer tool. 


Function 

FTSetConfig(hFT: FTHandle; thePtr: Ptr): INTEGER; 

Description 

FTSetConfig passes a null-terminated, C-style string (see the example string later in 
this section) to the file transfer tool for parsing. The string is pointed to by thePtr 
and must contain tokens that describe the configuration of the file transfer record. The 
string can be any length. 

FTSetConfig ignores items it does not recognize or find relevant; such an 
occurrence causes the file transfer tool to stop parsing the string and to return the 
character position where the error occurred. If the file transfer tool successfully parses 
the string, it retums ftNoErr. If the file transfer tool does not successfully parse the 
string, it retums one of the following values: a number less than -1 to indicate an osErr, 
-1 to indicate an unknown error, or a positive number to indicate the character position 
where parsing was stopped. 

Individual file transfer tools are responsible for the parsing operation. 

Sample 

A null-terminated, C-style configuration string 

InterCharDelay 0 InterLineDelay 0 Wordwrap False 

Ending CR\0 
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Transferring files 

when your appliation has performed the necessary steps described in the previous sections, it is 
ready to start transferring files. Your application must perform two steps: first, it must call 
FTStart to Open the file and initialize tool-private variables; second, it must call ftexcc to 
process data every time it goes through its main event loop. 

FTStart 

Starting a file transfer 

FTStart opens the file that is going to be involved in the file transfer, and initializes 
tool-private variables. 

The value in the owner field in the file transfer record controls the appearance of a 
status dialog box. 

The code that performs the actual sending, receiving, reading, and writing of data is 
the responsibility of your application. Your application specifies these routines when it 
creates the file transfer record. For a description of the parameters that will be passed to 
these routines, see “Routines Your Application Provides,” later in this chapter. 

Function FTStart(hFT: FTHandle; direction:FTDirection; 

fileinfo:SFReply): FTErr; 

Description direction describes the direction of the file transfer and can be either 

ftReceiving, ftTransmitting, Of ftFullDuplex. 

Once the file transfer has started, your application needs to call ftexoc every time 
it goes through its main event loop. Calling FTExec gives the tool time to send and 
receive a packet of data, amongst other things. 


Chapter 5: File Transfer Manager 


149 





FTExec 


Processing file transfer data 

FTExec is the soul of the file transfer process because it allows the file transfer tool to 


Procedure 

implement the file transfer protocol, ftexcc handles the disk input and output, either 
through your application or by performing local disk input and output, if specified by 
your application. Every time your application calls ftexcc, a little piece of data is 
processed until there is no more data. 

When sending files, the file transfer tool reads data from your application with 
readProc, and sends it to the connection with sendProc. When receiving files, the file 
transfer tool gets data from your application with recvProc, and checks if the data 
arrived correctly. The file transfer tool then writes the data with writeProc. 

readProc, sendProc, recvProc, and writeProc are discuSSed in “Routines 
Your Application Provides” later in this chapter. 

At the end of the file transfer, the file transfer tool is responsible for closing the file, 
releasing any memory allocated, and resetting the ftisFTMode bit in the file transfer 
record. 

FTExec(hFT: FTHandle); 

FTAbort 



Stopping a file transfer 

FTAbort aborts a file transfer in progress. The file transfer tool sends the appropriate 


Function 

canceling characters to the remote computer, and stops the file transfer. 

FTAbort(hFT: FTHandle): FTErr; 

FTDispose 



Disposing of a file transfer record 

FTDispose disposes of the file transfer record and all associated data structures. The 


Procedure 

file transfer tool stops any file transfer in progress (as specified by the file transfer 
record). 

FTDispose(hFT: FTHandle); 
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FTChoose retums one of the following values: 


CONST 

chooseDisaster = -2; 
chooseFailed = “1; 
chooseOKMinor = 1; 
chooseOKMajor = 2; 
chooseCancel * 3; 


ChooseDisaster means that the FTChoose operation failed, destroyed the 
file transfer record, and returned nil in the file transfer handle. 

ChooseFailed means that the FTChoose Operation failed and the file 
transfer record was not changed. 

ChooseOKMinor means that the user clicked OK in the dialog box, but did not 
change the file transfer tool being used. 

ChooseOKMa jor means that the user clicked OK in the dialog box and also 
changed the file transfer tool being used. The old file transfer handle is destroyed by 
the File Transfer Manager, by calling FTOispose. The file transfer is closed down, all 
pending read and write operations are terminated, and a new file transfer handle is 
returned in uft. 

chooseCancel means that the user clicked Cancel in the dialog box. 
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Custom configuration of a file transfer tool 

Your application creates a custom tool-settings dialog box and presents it to the user by using sbt 
File Transfer Manager routines: FTSetupPreflight, FTSetupSetup, FTSetupitem, 
FTSetupFiiter, FTSetupcaeanup, and FTSetupPostflight. Using these routines is 
more involved than calling FTChoose, but they provide your application with much more 
flexibility. Refer to the code sample in “The Custom Tool-Settings Dialog Box” in Appendix B to see 
how an application calls these routines. 

To build a list of file transfer tools, use the routine cRMCetindTooiName, which is described 
in Chapter 6. 


FTSetupPreflight 

Setting up the tool-settings dialog box 

FTSetupPref light retums a handle to a dialog item list that your application appends 
to the tool-settings dialog box. The handle comes from the file transfer tool. (The calling 
application uses AppendoiTL, discussed in Chapter 7.) This handle is not a resource 
handle. Your application is responsible for disposing of the handle when done with it. 

The file transfer tool can use FTSetupPref light to allocate a block of private 
storage, and to store the pointer to that block in magiccookie. magiccookie 
should be passed to the other routines that are used to set up the tool-settings dialog 
box. 

Function FTSetupPreflight(procID: INTEGER; VAR magicCookie: LONGINT): 

Handle; 

Description prociD is the ID for the file transfer tool that is being configured. Your application 

should get this value by using the FTCetProciD routine, discussed earlier in this 
chapter. 

♦ Note: The ref con of the custom tool-settings dialog box should point to a data 
structure (an example of which is shown next) in which the first two bytes are the tool 
prociD and the next four bytes are magiccookie. useritem routines, for 
example, may require prociD to obtain tool resources. 

TYPE 

chooseDLOGdata=RECORD 
prociD:INTEGER 
magiccookie:LONGINT 

END; 
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Handling events 

The File Transfer Manager event-processing routines provide useful extensions to the Macintosh 
Toolbox Event Manager. This section explains the three procedures that the Communications 
Toolbox provides: FTActivate, FTResume, and FTEvent. See “Other Events” in Chapter 2 for 
sample code showing how an application can determine if an event needs to be handled by one of 
these routines. 


FTActivate 

Activate events 

FTActivate processes an activate or deactivate event (for instance, installing or 
removing a custom tool menu) for a window associated with the file transfer. 

Procedure FTActivate(hFT: FTHandle; activate: BOOLEAN); 

Description If activate is true, the file transfer tool processes an activate event. Otherwise, it 

processes a deactivate event. 

FTRestime 

Resume events 

FTRe s ume is called when your application receives a suspend or a resume event. The file 
transfer tool may decide to change timeout values or other parameters, depending on 
whether or not the application is running in the foreground. 

Procedure FTResume(hFT: FTHandle; resume: BOOLEAN); 

Description If resume is TRUE , the file transfer tool processes a resume event. Otherwise, it 

processes a suspend event. 
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FTMenu 


Menu events 



Your application must call FTMenu when the user chooses an item from a menu 
installed by the file transfer tool. 

Function 

FTMenu(hFT: FTHandle; menuID: INTEGER; item: INTEGER): BOOLEAN; 

Description 

FTMenu retums FALSE if the file transfer tool did not handle the menu event. 

FTMenu retums true if the file transfer tool did handle the menu event. 


FTEvent 


Other events 

When your application receives an event, it should check if the ref con of the window 
is a tool’s hFT. Such an event occurs, for example, when the user clicks a button in a 
dialog box displayed by the file transfer tool. If it does belong to a file transfer tool’s 
window, your application can call FTEvent. 

Procedure 

FTEvent(hFT: FTHandle; theEvent: EventRecord); 

Description 

A window (or dialog box) created by a file transfer tool has a file transfer record handle 
stored in the refCon field for windowRecord. 
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Localizing configuration strings 

The Communications Toolbox provides two routines that make it easier to localize configuration 
strings. 


FTIntlToEnglish 

Translating into English 

FTIntlToEnglish conveits a Configuration string, which is pointed to by 
inputptr, to an American English configuration string pointed to by outputPtr. 

Function FTIntlToEnglish(hFT: FTHandle; inputPtr; Ptr; VAR outputPtr: 

Ptr; language: INTEGER): OSErr; 

Description This function returns an operating-system error code if any internal errors occur. 

The file transfer tool allocates space for outputPtr. Your application is responsible 
for disposing of the pointer with oisposPtr when done with it. 

language specifies the language from which the string is to be converted. Valid 
values for this field are shown in the description of the Script Manager in Inside 
Macintosh, Volume V. If the language specified is not supported, this routine returns 
noErr,but outputPtr is NIL. 


FTEnglishToInt1 

Translating from English 

FTEngiishTointi Converts an American English configuration string, which is 
pointed to by inputPtr, to a configuration string pointed to by outputPtr. 

Function FTEngiishTointi(hFT: FTHandle; inputPtr: Ptr; VAR outputPtr: 

Ptr; language: INTEGER): OSErr; 

Description This function returns an operating-system error code if any internal errors occur. 

The file transfer tool allocates space for outputPtr; your application is responsible 
for disposing of the pointer with oisposPtr when done with it. 

language specifies the language to which the string is to be converted. Valid values 
for this field are shown in the description of the Script Manager in Inside Macintosh, 
Volume V. If the language specified is not supported, noErr is still returned, but 

outputPtr is NIL. 
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Miscellaneous routines 

The routines described in this section perform a variety of tasks. 

FTGetToolName 

Getting the name of a tool 

FTGetToolName retums in name the name of the tool Specified by procio. 

Procedure FTGetToolName(procIO: INTEGER; VAR name; Str255); 

Description If procio references a file transfer tool that does not exist, the File Transfer Manager 

sets name to an empty string. 


FTSetRefCon 

Setting the file transfer record’s reference constant 

FTSetRefCon sets the file transfer record refcon to the given value. It is very 
important that your application use this routine to change the value of the reference 
constant, instead of changing it directly. 

Procedure FTSetRefCon(hFT: FTHandle; refCon: LONGINT); 


FTGetRefCon 

Getting the file transfer record reference constant 

FTGetRefCon retums the file transfer record reference constant. 
Function FTGetRefCon(AFT: FTHandle): LONGINT; 
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FTSetUserData 


Setting the userData field 

FTSetUserData sets the file transfer record’s userData field to the given value. It 
is very important that your application use this routine to change the value of the 
userData field, instead of changing it direcdy. 

Procedure FTSetUserData(hFT: FTHandle; userData: LONGINT); 


FTGetU s e rDat a 

Getting the userData field 

FTGetuserData retums the file transfer record’s userData field. 

Function FTGetuserData(hFT: FTHandle) : LONGINT; 

FTGetVersion 

Getting 'vers' resource information 

FTGetVersion retums a handle to a relocatable block that contains the information in 
the file transfer tool’s ' vers ' resource with ID=1. Your applications is responsible for 
disposing of the handle when done with it. 

♦ Note: The handle returned is not a resource handle. 

Function FTGetVersion(hFT: FTHandle): Handle; 


FTGetFTVersion 

Getting the File Transfer Manager version number 

FTGetFTVersion returns the version number of the File Transfer Manager. 
Function FTGetFTVersion: INTEGER; 

Description The version number of the File Transfer Manager described in this document is: 

CONST 

curFTVersion = 1/ 
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Routines your application provides 

Your appliation is responsible for providing routines it will use to send, receive, read, and write data 
during a file transfer. Your application might also need to include a routine that can provide 
information to the file transfer tool about the connection environment. When your application 
aeates a new file transfer record, it specifies pointers to these routines. 

Sending and receiving files are both two-step processes. When sending a file, the file transfer 
tool calls readProc to read the data into a buffer, and then sendProc to send the processed 
data. When receiving a file, the file transfer tool calls recvProc to get the data, and then 
writeProc to write the processed data to the appropriate medium. 

Your application must include the send and receive routines described in this section. The other 
routines are optional. 


readProc 

Reading data 

readProc is a routine in your application that the file transfer tool calls to read data into 
a buffer. 

Function readProc(VAR count: LONGINT; bufPtr: Ptr; refCon: LONGINT): 

OSErr; 

Description readProc must return an error code when appropriate. 

count is the number of bytes to read into the buffer. After readProc has 
completed, count contains the actual number of bytes that were read. 

bufPtr points to the buffer into which the data was read. 

ref Con is the reference constant of the file transfer record. 
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sendProc 


Sending data 

sendProc is 3 routine in your application that the file transfer tool calls to send data 
that is in a buffer. 

Function sendProc(thePtr: Ptr; theSize: LONGINT; refCon: LONGINT; 

channel: CMChannel; flags: CMFlags):LONGINT; 

Description sendProc must retum the actual number of bytes it sent. 

thePtr is a pointer to a block of data in memory that is to be sent. 

thesize is the length of that block. 

refcon is the reference constant of the file transfer record. 

channel Specifies the channel that the file transfer tool can use. Your application should 
specify one of the following values for channel: CMOata, CMCnti, or CMAttn. 

flags is described in Chapter 3 under the description of cMwrite. 

Sample send routine 

FUNCTION sendProc(thePtr: Ptr;theSize; LONGINT;refcon: LONGINT; 

channel: CMChannel;flags: INTEGER) : LONGINT; 

VAR 

theErr : CMErr; { Errors on a write } 

BEGIN 

sendProc:= 0; { Assume the worst } 

IF gConn <> NIL THEN BEGIN { Send the data } 

theErr := CMWrite(gConn,thePtr,theSize,channel,FALSE, NIL, 0, flags) 
IF (theErr = noErr) THEN 

sendProc:= theSize { if ok, we sent all } 

ELSE 

; { Handle errors } 

END; { Good Connection } 

END; { sendProc } 
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recvProc 


Receiving data 


recvProc is 3 routine in your application that the file transfer tool uses to receive data 
into a buffer from the connection. 

Function recvProc(thePtr: Ptr; theSize: LONGINT; refCon; LONGINT; 

channel: CMChannel; VAR flags: CMFlags):LONGINT; 

Description recvProc must return the actual number of bytes it received. 

thePtr is a pointer to a block of data in memory where the incoming data is to be 
placed. 

thesize is the length of that data. 

ref Con is the reference constant of the file transfer record. 

channel specifies the data channel that the file transfer tool can use. Your application 
should specify one of the following values for channel: cMOata, cMCnti, or cMAttn. 

flags is described in Chapter 3 under the description of cMRead. 

Sample receive routine 

FUNCTION recvProc(thePtr: Ptr;theSize: LONGINT;refcon: LONGINT; 

channel: CMChannel;VAR flags: INTEGER): LONGINT; 

VAR 

theErr : CMErr; { Any errors } 

BEGIN 

recvProc:= 0; { Assume the worst } 

IF gConn <> NIL THEN BEGIN 

{ Read all the data } 

theErr ; = CMRead(gConn,thePtr,theSize,channel,FALSE,NIL,0,flags); 
IF (theErr <> noErr) THEN 

recvProc:= theSize { if ok, we got all } 

ELSE 

; { Handle errors } 

END; { Good Connection } 

END; { recvProc } 
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writeProc 


Writing data 

writeProc is a routine in your application that the file transfer tool uses to write data 



from a buffer. 

Function 

writeProc(VAR count; LONGINT; bufPtr: Ptr; refCon; LONGINT): 

OSErr; 

Description 

writeProc must retum an error code when appropriate. 

count is the number of bytes to write. After writeProc has completed, count 
contains the actual number of bytes written. 

bufPtr is a pointer to the data in memory. 

refCon is the reference constant of the file transfer record. 


environsProc 


Getting the connection environment 

Sometimes the file transfer tool needs to know about the type of connection on which to 



transfer files. For example, some file transfer protocols require an 8-bit data channel. To get 
this information, the file transfer tool calls a routine in your application, environsProc. 

Function 

environsProc(refCon: LONGINT; VAR theEnvirons: ConnEnvironRec); 

CMErr; 

Description 

refCon is the reference constant of the file transfer record. 

theEnvirons is a data Structure containing the connection-environment record. Your 
application can either construct theEnvirons or use the Connection Manager routine 
CMGetConnEnvirons. For more information about theEnvirons, See 
“CMGetConnEnvirons ; Getting the Connection Environment” in Chapter 3. 

The example that follows shows how environsProc can point to a Connection 
Manager routine to retrieve information about the connection environment. 


Sample connection-environment routine 

FUNCTION environsProc(refCon: LONGINT;VAR theEnvirons: ConnEnvironRec): OSErr; 
BEGIN 

environsProc:= envNotPresent; { pessimism } 

{ Get the connection info } 

IF gConn <> NIL THEN { Tool sets the version } 

environsProc:= CMGetConnEnvirons(gConn,theEnvirons); 

END; { environsProc } 
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Quick reference 

This section provides a reference to File Transfer Manager routines and data structures. At the end 
of this section is a listing of routine selectors for programming in assembly language. 

Routines 

FUe Transfer Manager routines See page 

FTAbort(hFT: FTHandle): FTErr; 150 

FTActivate(hFT: FTHandle; activate: BOOLEAN); 151 

FTChoose(VAR hFT: FTHandle; where: Point; idleProc: 142 

ProcPtr): INTEGER; 

FTDefault(VAR theConfig: Ptr; procID: INTEGER; 141 

allocate: BOOLEAN); 

FTDispose(hFT: FTHandle); 150 

FTEnglishToIntl(hFT: FTHandle; inputPtr: Ptr; VAR 155 

outputPtr: Ptr; language: INTEGER): OSErr; 

FTEvent(hFT: FTHandle; theEvent: EventRecord); 152 

FTExec(hFT: FTHandle); 150 

FTGetConfig(hFT: FTHandle): Ptr; 148 

FTGetFTVersion: INTEGER; 155 

FTGetToolName(procID: INTEGER; VAR name: Str255); 155 

FTGetProcID(name: Str255): INTEGER; 159 

FTGetRefCon(hFT: FTHandle): LONGINT; 154 

FTGetUserData(hFT: FTHandle) : LONGINT; 155 

FTGetVersion(hFT: FTHandle): Handle; 155 

FTIntlToEnglish(hFT: FTHandle; inputPtr: Ptr; VAR 155 

outputPtr: Ptr; language: INTEGER): OSErr; 

FTMenu(hFT: FTHandle; menuID: INTEGER; item: 152 

INTEGER): BOOLEAN; 

FTNew(procID: INTEGER; flags: FTFlags; sendProc: 159 

ProcPtr; recvProc: ProcPtr; readProc: ProcPtr; 
writeProc: ProcPtr; environsProc: ProcPtr; owner: 

WindowPtr; refCon: LONGINT; userData: LONGINT): 

FTHandle; 

FTResume(hFT: FTHandle; resume: BOOLEAN); 151 

FTSetConfig(hFT: FTHandle; thePtr: Ptr): INTEGER; 148 

FTSetRefCon(hFT: FTHandle; refCon: LONGINT); 154 
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File Transfer Manager routines See page 


FTSetupCleanup(procID: INTEGER; theConfig: Ptr; 146 

count: INTEGER; theDialog: DialogPtr; VAR 
magicCookie: LONGINT); 

FTSetupFilter(procID: INTEGER; theConfig: Ptr; count: 145 

INTEGER; theDialog: DialogPtr; VAR theEvent: 

EventRecord; VAR theltem: INTEGER; VAR magicCookie: 

LONGINT): BOOLEAN; 

FTSetupItem(procID: INTEGER; theConfig: Ptr; count: 146 

INTEGER; theDialog: DialogPtr; VAR theltem: INTEGER; 

VAR magicCookie: LONGINT); 

FTSetupPostflight(procID:INTEGER); 147 

FTSetupPreflight(procID: INTEGER; VAR magicCookie: 144 

LONGINT): Handle; 

FTSetupSetup(procID: INTEGER; theConfig; Ptr; count: 145 

INTEGER; theDialog: DialogPtr; VAR magicCookie: 

LONGINT); 

FTSetUserData(hFT: FTHandle; userData: LONGINT); 155 

FTStart(hFT: FTHandle; direction: FTDirection; 149 

fileinfo: SFReply): FTErr; 

FTValidate(hFT: FTHandle): BOOLEAN; 141 

InitFT: FTErr; 138 

Routines in your application See page 


environsProc(refCon: LONGINT; VAR theEnvirons: 159 

ConnEnvironRec): CMErr; 

readProc(VAR count: LONGINT; bufPtr: Ptr; refCon: 156 

LONGINT):OSErr; 

recvProc(thePtr: Ptr; theSize: LONGINT; refCon: 158 

LONGINT; channel; CMChannel; VAR flags: 

CMFlags):LONGINT; 

sendProc(thePtr: Ptr; theSize: LONGINT; refCon: 157 

LONGINT; channel: CMChannel; flags: CMFlags):LONGINT; 

writeProc(VAR count: LONGINT; bufPtr: Ptr; refCon: 159 

LONGINT): OSErr; 
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File transfer record 


TYPE 


FTHandle 

'"FTPtr; 

FTPtr 

'"FTRecord; 

FTRecord 

PACKED RECORD 

procID : 

INTEGER; 


flags 

errCode 

: FTFlags; 

: FTErr; 

refCon 

: LONGINT; 

userData 

: LONGINT; 

defProc 

: ProcPtr; 

config 

oldConfig 

: Ptr; 

: Ptr; 

environsProc 

ProcPtr; 

reservedl 

LONGINT; 

reserved2 

LONGINT; 

ftPrivate 

: Ptr; 

sendProc 

ProcPtr; 

recvProc 

ProcPtr; 

writeProc 

ProcPtr; 

readProc 

ProcPtr; 

owner 

: WindowPtr; 

direction 

: FTDirection; 

theReply : 

: SFReply; 

writePtr 

LONGINT; 

readPtr 

LONGINT; 

theBuf 

'"char; 

bufSize 

LONGINT; 

autoRec 

Str255; 

attributes 

FTAttributes; 

END; 
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Constants and data types 

CONST 

curFTVersion 

TYPE 

FTDirection 

CONST 

ftReceiving 
ftTransmitting 
ftFullDuplex 


{ file transfer attributes } 
TYPE 

FTAttributes 

CONST 

ftSameCircuit = 

ftSendDisable 
ftReceiveDisable = 

ftTextOnly 


{ file transfer flags } 
TYPE 

FTFlags 


CONST 

ftIsFTMode 
ftNoMenus 
ftQuiet 
ftSucc 

{ Choose return values } 
CONST 

chooseDisaster 
chooseFailed 
chooseOKMinor 
chooseOKMajor 
chooseCancel 


1 / 


INTEGER 


0 ; 

1 ; 

2 ; 


INTEGER 

$ 0001 ; 

$ 0002 ; 

$0004; 

$0008; 


LONGINT 


$ 0001 ; 

$ 0002 ; 

$0004; 

$0080; 


-2 

-1 

1 

2 

3 
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Errors 




TYPE 





FTErr 

= 

OSErr; 

CONST 





ftGenericError 

= 

-1; 


ftNoErr 

= 

0; 


ftRejected 

= 

1; 


ftFailed 

= 

2; 


ftTimeOut 

= 

3; 


ftTooManyRetry 

= 

4 ; 


ftNotEnoughDspace 

= 

5; 


ftRemoteCancel 


6/ 


ftWrongFormat 

= 

7; 


ftNoTools 

=s 

8/ 


ftUserCancel 

= 

9; 


ftNotSupported 

= 

10; 


File Transfer Manager routine selectors 

♦ Assembly note: The Communications Toolbox routines are accessed via a Macintosh 
Operating System trap, ao contains a pointer to the routine parameters. You can call each 
of the Communications Tooolbox routines with a macro that has the same name as the 
routine preceded by an underscore. When expanded, these macros put the routine selector 
onto the stack, set ao to point to the selector, invoke the trap macro _comTooiTrap 
($A 08 B), and finally pop the routine selector back off the stack. It is your application’s 
responsibility to remove the parameters. 


FTAbort 

.EQU 

525 

FTGetProcID 

.EQU 

519 

FTActivate 

.EQU 

544 

FTGetRefCon 

.EQU 

515 

FTChoose 

.EQU 

540 

FTGetToolName 

.EQU 

518 

FTDefault 

.EQU 

528 

FTGetUserData 

.EQU 

517 

FTDispose 

.EQU 

521 

FTGetVersion 

.EQU 

538 

FTEnglishToIntl 

.EQU 

537 

FTIntlToEnglish 

.EQU 

536 

FTEvent 

.EQU 

541 

FTMenu 

.EQU 

543 

FTExec 

.EQU 

522 

FTNew 

.EQU 

520 

FTGetConfig 

.EQU 

534 

FTResume 

.EQU 

526 

FTGetFTVersion 

.EQU 

539 

FTSetConfig 

.EQU 

535 
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FTSetRefCon 

.EQU 

514 

FTSetupCleanup 

.EQU 

533 

FTSetupFilter 

.EQU 

531 

FTSetupItem 

.EQU 

532 

FTSetupPostflight 

.EQU 

542 

FTSetupPreflight 

.EQU 

529 


FTSetupSetup 

.EQU 

530 

FTSetUserData 

.EQU 

516 

FTStart 

.EQU 

523 

FTValidate 

.EQU 

527 

InitFT 

.EQU 

513 
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Chapter 6 Communications Resource Manager 







































































THIS CHAPTER describes the Communications Resource Manager, the 
Communications Toolbox manager that makes it easier for your code to 
manage communications resources and devices. This chapter describes the 
data structures and routines your code can use to implement device 
management. Next, it presents the routines your code can use to perform 
resource management. At the end of the chapter, you’ll find a “Quick 
Reference” to routines, data structures, and routine selectors for 
programming in assembly language. 

In this chapter, the term your code refers to the application, tool, or driver you 
are writing for the Macintosh, which will implement communications 
services for users. 

To use the Communications Resource Manager, you need to be familiar with 

■ the Resource Manager (described in Inside Macintosh, Volumes I, IV, V) 

■ the Device Manager (described in Inside Macintosh, Volumes I, IV, V) 

■ the Memory Manager (described in Inside Macintosh, Volumes I, IV, V) 

■ the Operating System Utilities (described in Inside Macintosh, Volume II) 

■ the MultiFinder programming environment (described in Programmer’s 
Guide to MultiFinder) 
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About the Communications Resource Manager 

Your code uses the services provided by the Communications Resource Manager for two purposes: 
to manage devices (such as internal modems and serial cards) and to manage resources. Device 
management is essential when your code needs to know about new cards that have been installed 
in a Macintosh. Resource management is required when your code is sharing resources with other 
applications (as it does when a Macintosh runs under MultiFinder). The resource management 
services provided by the Communications Resource Manager are an extension to the services 
provided by the Resource Manager in the Macintosh Toolbox. 

The way your code uses the Communications Resource Manager is very similar to the way it 
uses other Communications Toolbox managers. Your code calls a Communications Resource 
Manager routine, which, upon completion, returns to your code any relevant parameters and return 
codes. Figure 6-1 shows the data flow into and out of the Communications Resource Manager. 

■ Figure 6-1 Data flow into and out of the Communications Resource Manager 
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Device fflanagement 

The way Macintosh applications interact with special interface cards varies from card to card, 
making the task of programming the Macintosh to use these cards quite complex. The 
Communications Toolbox solves this problem by providing applications with standardized routines 
and data structures that they can use to keep track of communications devices users have installed. 

The data structure that is most important in supporting communications device management 
is the conununications resource record, which is stored as an operating system queue. The 
communications resource record comprises fields containing information such as the type of device 
the record represents, and whether or not the device is available for use. The communications 
resource record is described later in this chapter. 

The Communications Resource Manager and your code keep track of communications devices 
by placing a communiations resource record into the queue for each communications device. 
Initially, when your code calls initCRM (discussed later in this chapter), this queue contains two 
records, one for each of the serial drivers. Your code can then add and delete communications 
resource records. 

By making use of Communications Toolbox routines, your code can register new devices, 
allocate devices, and look for specific kinds of devices. And device drivers, if properly coded, can 
resolve conflicts when two or more applications need to use a communications resource at the 
same time. This situation often arises in a MultiFinder environment. 


Resource management 

when your code shares resources with other applications, problems can arise if one of the 
applications accidentally disposes of a resource needed by another application. The Communications 
Toolbox provides routines that your code can use to share resources without confronting this kind 
of problem. These routines keep track of how many times a resource is simultaneously in use in an 
internal Communications Resource Manager data structure for every communications resource. 
Every time code requests a resource, the Communications Resource Manager increases the “use 
count” for that resource by 1. Every time code releases a communications resource, the 
Communications Resource Manager decreases ihe value by 1. This enables the Communications 
Resource Manager to keep track of which resources are being used; when a resource’s use count 
reaches 0, it is released. 
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The cofflfflunications resource record 


The most important data structure to the Communications Resource Manager is the 
communications resource record. It contains information like the name and type of each device 
connected to the Macintosh, and whether or not a device is in use. 

At startup time, the Communications Resource Manager builds a queue of communications 
resource records. If the Communications Resource Manager is installed, the queue will consist of a 
minimum of two devices of type crmseriaioevice. 

When your code installs a new record into the queue, it must fill in the following fields in the 
communications resource record: crmOevicelype, crmAttributes, crmStatus, and 
crmRefcon. The Communications Resource Manager fills in the other fields. 


Communications resource record data structure 


TYPE 


CRMRecPtr 

= 

^CRMRec; 

CRMRec 

= 

RECORD 

qLink 


QElemPtr 

qType 


INTEGER; 

crmVersion 


INTEGER; 


crmPrivate : 

LONGINT; 

crmReserved : 

INTEGER; 

crmDeviceType : 

LONGINT; 

crmDevicelD : 

LONGINT; 

crmAttributes : 

LONGINT; 

crmStatus ; 

LONGINT; 

crmRefCon : 

LONGINT; 


END; 


qLlnk 

qLink points to the next CRMRec in the Communications Resource Manager’s queue of 
communiations resource records. 

qType 

qType is a constant that your code must fill with the constant crmiype. 

crmVersion 

crtnversion is the version number of the CRMRec data structure. At this time there is only one 
version, so the Communications Resource Manager fills this with the constant crmRecversion. 
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crmPrivate and crmReserved 

crmPrivate and crmReserved are private to the Communications Resource Manager; your 
code must not use them. 

crmDeviceType 

crmDeviceType is the type of device. For example, a Serial pOIt haS a crmDeviceType of 
crmSerialDevice. 

crmDevicelD 

crmDeviceiD is an identifier that your code can use to distinguish between multiple devices of 
the same device type. The Communications Resource Manager fills in this field when your code calls 
the CRMinstaii routine. 

crmAttributes 

crmAttributes specifies the attributes of a specific device type. This field can hold either a 
pointer to the data or the actual data that describes the device. A sample crmAttributes data 
structure appears later in this chapter in the section “Registering a Device.” 

crmStatus 

crmstatus specifies the status of a device. Your code can use this field for device arbitration 
purposes. 

crmRefCon 

crmRefcon is not used in this release of the Communications Resource Manager. 
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Communications Resource Manager routines 

The following sections describe the routines that applications use to access Communications 
Resource Manager services. Your application can not call these routines from interrupt level. 

Below is a listing of the routines described in this section in the order in which they are 
presented. You can use the list as a reference tool to find the description of a routine. Or, you can 
use the index at the end of this document, which lists these routines alphabetically. 

InitCRM / 174 
CRMInstall / 174 
CRMSearch / 175 
CRMRemove / 175 
CRMGetCRMVersion / 176 
CRMGetHeader / 176 
CRMGetResource / 177 
CRMGetlResource / 177 
CRMGetIndResource / 177 


CRMGetlIndResource / 177 
CRMGetNamedResource / 178 
CRMGetlNamedResource / 178 
CRMGetIndex / 178 
CRMReleaseResource / 178 
CRMGet I ndToolName / 179 
CRMRealToLocallD / 180 
CRMLocalToRealID / 181 
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InitCRM 


Initializing the Communications Resource Manager 

InitCRM initializes the Communications Resource Manager. 



A Warning Your code must call this routine after calling the standard Macintosh 

Toolbox initialization routines and before calling any of the other Communications 

Toolbox manager initialization routines, a 

Function 

InitCRM:CRMErr; 

Description 

InitCRM returns an operating-system error code if appropriate. Valid values are as 
follows; 

TYPE 

CRMErr = OSErr; 

CONST 

crmGenericError = -1; 

crmNoErr = 0/ 

Your code must check for the presence of the Communications Toolbox before calling 
this function. Sample code under “Determining Whether the Managers are Installed” in 
Appendix B shows you how your application can make this check. 


CRMInstall 


Installing devices 

CRMInstall installs a device into the Communications Resource Manager’s queue. 


Procedure 

Devices in the Communications Resource Manager queue typically have their cRMRec 
records allocated in the system heap. If your code installs a CRMRec at startup time, be 
sure that your code increases the size of the system heap appropriately. 

For more information on how to register a device with the Communications Resource 
Manager, read “Registering a Device,” later in this chapter. 

CRMInstall(CrmReqPtr: QElemPtr); 

Description 

CRMInstall installs the communications resource record crmReqPtr into the 
Communications Resource Manager queue. 


A Warning A CRMRec allocated in the appliation heap needs to be removed before the 
application heap is reinitialized; otherwise, the Communications Resource Manager queue 
may be damaged, a 
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CRMSearch 


Searching for devices 

Your code can use CRMSearch to order the Communications Resource Manager queue, 


Function 

or to add new elements to the end of the queue. 

CRMSearch(crmReqPtr: QElemPtr): QElemPtr; 

Description 

crmReqPtr Specifies communications resource record search criteria. 

CRMSearch searches for a device in the Communications Resource Manager queue 
that has two characteristics; the same deviceType, and a deviceio greater than 
the deviceiD in the record specified by crmReqPtr. CRMSearch returns a pointer 
to the first record that it finds that meets these two conditions. Or, if no records meet 
the search criteria, it returns nil. 

When searching for the first element in the queue, your code must pass 0 in 

devicelD. 

CRMRemove 



Removing devices 

CRMRemove removes a device from the Communications Resource Manager queue. 


Function 

CRMRemove(crmReqPtr: QElemPtr): OSErr; 

Description 

crmReqPtr Specifies the device to be removed. 
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CRMGetCRMVersion 


Getting the version number 



CRMGetcRMVersion retums the version number of the Communications Resource 
Manager. 

Function 

CRMGetcRMVersion:INTEGER; 

Description 

The Communications Resource Manager version described in this document is: 

CONST 

curCRMVersion = 1; 


CRMGetHeader 


Getting to the head of the queue 


Function 

CRMGetHeader retums a pointer to the head of the Communications Resource Manager 
queue. 

CRMGetHeader: QHdrPtr; 
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Resource management routines 

The nine routines described in this section make it easier for your code to manage communications 
resources. Your code should use these routines so that the Communications Resource Manager can 
keep track of how many times a resource is simultaneously in use. 

The names of these routines are similar to the names of Resource Manager routines available in the 
Macintosh Toolbox. Communications Resource Manager routines also operate very much like Resource 
Manager routines; in fact, most of them make use of their counterparts in the Macintosh Toolbox. 


CRMGetResource and CRMGetlResource 

Loading resources 

CRMGetResource and CRMGetlResource Call the Resource Manager routines 
GetResource and GetiResource , respectively, and return a handle to the specified 
communications resource. The Communications Resource Manager then adds the handle 
to the list of resources that it is managing, and increases by one use count, which 
indicates how many pieces of code are using a resource. 

Function CRMGetResource(theType: ResType; thelD: INTEGER): Handle; 

Function CRMGetlResource(theType: ResType; thelD: INTEGER): Handle; 


CRMGetIndResource and CRMGetllndResource 


Loading indexed resources 

CRMGetIndResource and CRMGetllndResource Call the Resource Manager 
routines GetindResource and GetiindResource, respectively, and return a 
handle to the specified communications resource. The Communications Resource Manager 
then adds the handle to the list of resources that it is managing, and increases by one the 
use count, which indicates how many pieces of code are using a resource. 


Function 

Function 


CRMGetIndResource(theType: ResType; 
CRMGetllndResource(theType: ResType; 


index: 

index: 


INTEGER): Handle; 
INTEGER): Handle; 
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CRMGetNamedResource and CRMGetlNamedResource 


Loading named resources 

CRMGetNamedResource and CRMGetlNamedResource call 
GetNamedResource and GetiNamedResource, respectively, and return a handle to 
the specified communications resource. The Communications Resource Manager then 
adds the handle to the list of resources that it is managing, and increases by one the use 
count, which indicates how many pieces of code are using a resource. 

Function CRMGetNamedResource(theType: ResType; name: Str255) : Handle; 

Function CRMGetlNamedResource(theType: ResType; name: Str255): Handle; 


CRMGet Index 

Getting a usage index for a resource 

CRMGet Index retums a use count which indicates how many pieces of code are 
simultaneously using a resource with the specified handle. cRMGetindex retums 0 if it 
does not find theHandie in the list of resources the Communications Resource 
Manager is managing. 


Function CRMGetIndex(theHandie: Handle): LONGINT; 


CRMReleaseResource 


Releasing resources 

CRMReleaseResource decreases by 1 the value that indicates how many pieces of 
code have requested a resource. If the use count reaches 0, the resource specified by 
theHandie is released with a call to the Resource Manager routine 

ReleaseResource. 

Procedure CRMReleaseResource(theHandie: Handle); 

A Warning Your code must release communications resources by calling 

CRMReleaseResource. If your code tries to release the resources using the Resource 
Manager routine ReieaseResource, the results are unpredictable, a 
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CRMGetIndToolName 


Getting the 


Function 


Description 


name of a tool 

CRMGetIndToolName retums the name of a tool in toolName. 

CRMGetIndToolName(bundleType : OSType; index : INTEGER; VAR 
toolName : Str255) : OSErr; 

The appropriate values for bundleType are as follows: 

CONST 

ClassCM = 'cbnd'; 

ClassFT = 'fbnd'; 

ClassTM = 'tbnd'; 

index specifies which occurrence of a particular type of tool to return. For example, if 
index is 2, the Communications Resource Manager retums the name of the second tool 
of a particular type in toolName. If the Communications Resource Manager cannot find 
a tool that matches the specified parameters, an empty string is returned in toolName. 
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Resource-mapping routines 

All resources used by a tool can be referenced by a local ID, which can be mapped (using the tool 
bundle resource) into the appropriate physical ID. The Communications Toolbox contains two 
routines that will help you keep things straight: To map from physical ID to local ID, use 
CRMRealToLocallD; tO map from local ID to physical ID, use CRMLocalToReallO. 


CRMRealToLocalID 

Mapping to Local ID 

CRMRealToLocallD maps a physical resource ID to a local resource ID. 

Function CRMRealToLocallD(bundleType: ResType; toolID: INTEGER; theKind: 

ResType; realID: INTEGER): INTEGER; 

Description This routine returns the (physical/local) resource ID if an appropriate entry exists in the 

tool bundle resource. If no entry is found, -1 is returned. 

bundleType specifies the type of tool for which the mapping is to take place: 
ciassCM (for connection tools), ciassTM (for terminal tools), or ciassFT (for file 
transfer tools). 

Here is the format for a connection tool bundle resource (in Rez format). The same 
resource type declaration holds for terminal tools and file transfer tools. 

type 'cbnd' { /* or tbnd, or fbnd */ 

integer = $$CountOf(TypeArray) - 1; 

array TypeArray { 

literal longint; /* Type */ 

integer = $$CountOf(IDArray) - 1; 
wide array IDArray { 

integer; /* Local ID */ 

integer; /* Actual ID */ 

}; 

}; 

}/ 
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CRMLocalToRealID 


Mapping to Real ID 



CRMLocalToRealID maps a local resource ID to a physical resource. 

Function 

CRMLocalToRealID(bundleType: ResType; toolID; INTEGER; theKind: 
ResType; locallD: INTEGER); INTEGER; 

Description 

This routine returns the (physical/local) resource ID if an appropriate entry exists in the 
tool bundle resource. If no entry is found, -1 is returned. 

bundleType specifies the type of tool for which the mapping is to take place; 
ciassCM (for connection tools), ciassTM (for terminal tools), or ciassFT (for file 
transfer tools). 

tooiiD specifies the bundle resource for the tool. 
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Registering a device 

This section gives some basic information about writing drivers that emulate the behavior of the 
built-in serial drivers. 


Private storage Your code can reference all private data storage off the dctistorage field 
of the DCtiEntry for the drivers involved. 


Low memory Do not use any. 


Driver naming Use unique driver names and be prepared to deal with driver name collisions. 
For example, don’t use . c i n /. cout. 

driver csCode calk Support all of the cscode calls supported by the standard serial drivers. If 
you need additional csCode calls, contact Developer Technical Support to 
reserve them. csCode calls below 256 are reserved for Apple Computer 


Data structures 

Each device in the Communications Resource Manager’s queue has a CRMRec associated with it. 
For the crmoeviceType field, Apple Computer, has defined the following value for serial port 
devices: 

CONST 

crmSerialDevice = 1; 


♦ Note: Values for crmDeviceType less than 128 are reserved for Apple Computer Your 
code must not use them. 


When adding a CRMRec to the Communications Resource Manager queue with the crm install 
routine, pass 0 for the crmoeviceiD field. The device identifier will be assigned by the 
Communications Resource Manager. 

The crmAttributes field in the CRMRec points to a serial port device-specific data 
structure. The crmstatus field of the crmrcc is not used for devices of type 
crmSerialDevice in this version of the Communications Resource Manager. 
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TYPE 


CRMSerialPtr 

CRMSerialRecord 

version 


'"CRMSerialRecord; 

RECORD 

INTEGER; 


inputDriverName 
outputDriverName 
name 


StringHandle; 

StringHandle; 

StringHandle; 


devicelcon 


Handle; 


ratedSpeed 

maxSpeed 


LONGINT; 

LONGINT; 


reserved 

END; 


LONGINT; 


version 

version is the version number of the CRMSeriaiRecord data structure. For the version of 
CRMSerialRecord described in this document, version = curCRMSerRecVer, which 

equals 0. 

inputDrIverName 

inputDriverName is a pointer to a Pascal-style string, which is the name of the input driver for 
the given serial port. This driver should behave like the standard input serial port drivers (.Ain and 
.Bln), and support the same cscode calls as do the standard drivers. 

outputDrIverName 

outputDriverName is a pointer to a Pascal-style string, which is the name of the output driver 
for the given serial port. This driver should behave like the standard output serial port drivers 
(.AOut and .BOut), and support the same cscode calls as do the standard drivers. 

name 

name is a String handle, which is the name associated with a given port. 

devicelcon 

devicelcon is a handle to a relocatable block that contains an icon and a mask associated with 
the given port. Pass nil if no icon is available. 

ratedSpeed 

ratedSpeed is the maximum recommended speed in bits per second. 

maxSpeed 

maxSpeed is the maximum speed in bits per second of which the hardware is capable. 
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Searching for serial port devices 

The following routine will search the Communications Resource Manager linked list for devices of a 
specified type. 

PROCEDURE FindSerialPorts; 

VAR 


BEGIN 


theCRM ; 

CRMRecPtr; 

theCRMRec : 

CRMRec; 

theErr : 

RMErr; 

theSerial : 

CRMSerialPtr; 

old : 

INTEGER; 

theErr := 0; 


old := 0; 


WHILE (theErr = 

noErr) DO 

BEGIN 



{ error status } 

{ index number of ports } 


WITH theCRMRec DO 
BEGIN 

crmDeviceType := crmSerialDevice; 

{ search for port with index number greater than "old" } 
crmDevicelD := old; { to be filled in later } 

END; 

theCRM := QtheCRMRec; 

theCRM ;= CRMRecPtr(CRMSearch(QElemPtr(theCRM))); 

IF theCRM <> NIL THEN { got one! } 

BEGIN 

theSerial := CRMSerialPtr (theCRM'^. crmAttributes) ; 
old := theCRM'^. crmDevicelD; 


WITH theSerial'" DO 

BEGIN 

END; 


END 

ELSE 

BEGIN 


theErr := 1; 


END; 

END; { while } 


END; 
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Quick reference 

This section provides a reference to Communications Resource Manager routines and data 
structures. At the end of this section is a listing of routine selectors for programming in assembly 
language. 

Routines 

Communications Resource Manager routines See page 

CRMGetlIndResource(theType: ResType; index: INTEGER): 177 

Handle; 

CRMGetlNamedResource(theType: ResType; name: Str255): 178 

Handle; 

CRMGetlResource(theType: ResType; thelD: INTEGER): 177 

Handle; 

CRMGetCRMVersion: INTEGER; 176 

CRMGetHeader: QHdrPtr; 176 

CRMGetIndex(theHandle: Handle): LONGINT; 178 

CRMGetIndResource(theType: ResType; index: INTEGER): 177 

Handle; 

CRMGetIndToolName(bundleType : OSType; index : 179 

INTEGER; VAR toolName : Str255) : OSErr; 

CRMGetNamedResource(theType: ResType; name: Str255): 178 

Handle; 

CRMGetResource(theType: ResType; thelD: INTEGER): 177 

Handle; 

CRMInstall(crmReqPtr: QElemPtr); 174 

CRMReleaseResource(theHandle: Handle); 178 

CRMRemove(crmReqPtr: QElemPtr): OSErr; 175 

CRMSearch(crmReqPtr: QElemPtr): QElemPtr; 175 

CRMLocalToRealID(bundleType: ResType; toolID: 181 

INTEGER; theKind: ResType; locallD: INTEGER): 

INTEGER; 

CRMRealToLocallD(bundleType: ResType; toolID: 180 

INTEGER; theKind: ResType; realID: INTEGER): INTEGER; 

InitCRM:CRMErr; 174 
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Constants and data types 

TYPE 

CRMErr = OSErr; 


CONST 

crmGenericError = -1; 

crmNoErr = 0; 


CONST 


curCRMVersion = 1; 

{ Communications Resource Manager linked list type } 
crmType = 9; 

{ Version of CRMRec data structure } 
crmRecVersion = 1; 

{ local/real resource ID mapping } 


ClassCM 

= 

'cbnd'/ 

ClassTM 

= 

'tbnd'; 

ClassFT 

ss 

'fbnd'/ 


TYPE 


CRMRecPtr 

CRMRec 

qLink 

qType 

crmVersion 

= '"CRMRec; 

= RECORD 

QElemPtr 

INTEGER; 

INTEGER; 


crmPrivate : 

crmReserved : 

: LONGINT; 

; INTEGER; 


crmDeviceType 

crmDevicelD 

crmAttributes 

crmStatus 

LONGINT; 

LONGINT; 

LONGINT; 

LONGINT; 

END; 

crmRefCon ; 

LONGINT; 
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TYPE 


CRMSerialPtr 


'^CRMSerialRecord; 


lalRecord 

= 

RECORD 

version 

: 

INTEGER; 

inputDriverName 


StringHandle; 

outputDriverName 


StringHandle; 

name 


StringHandle; 

devicelcon 


Handle; 

ratedSpeed 

: 

LONGINT; 

maxSpeed 


LONGINT; 

reserved 


LONGINT; 


END; 


Communications Resource Manager routine selectors 

♦ Assembly note: The Communications Toolbox routines are accessed via a Macintosh 

Operating System trap, ao contains a pointer to the routine parameters. You can call each 
of the Communications Tooolbox routines with a macro that has the same name as the 
routine preceded by an underscore. When expanded, these macros put the routine selector 
onto the stack, set ao to point to the selector, invoke the trap macro _comTooiTrap 
($A08B) , and finally pop the routine selector back off the stack. It is your application’s 
responsibility to remove the parameters. 


CRMGet1IndResource 

.EQU 

1290 

CRMGetResource 

.EQU 

1287 

CRMGetlNamedResource 

.EQU 

1292 

CRMInstall 

.EQU 

1283 

CRMGetlResource 

.EQU 

1288 

CRMLocalToRealID 

.EQU 

1295 

CRMGetCRMVersion 

.EQU 

1286 

CRMRealToLocallD 

.EQU 

1296 

CRMGetHeader 

.EQU 

1282 

CRMReleaseResource 

.EQU 

1293 

CRMGetIndex 

.EQU 

1294 

CRMRemove 

.EQU 

1284 

CRMGetIndResource 

.EQU 

1289 

CRMSearch 

.EQU 

1285 

CRMGetIndToolName 

.EQU 

1297 

InitCRM 

.EQU 

1281 

CRMGetNamedResource 

.EQU 

1291 
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THIS CHAPTER describes the Communiations Toolbox utilities, a set 
of routines that makes it easier for your application to manipulate dialog item 
lists, control pop-up menus, and search a network for AppleTalk entities. This 
chapter also details two routines your application can use to initialize the 
utilities and obtain the version number of the utilities. 

At the end of the chapter you’ll find a “Quick Reference” to these routines, 
data structures, and routine selectors for programming in assembly language. 

To use the dialog item list manipulation routines, you need to be familiar with 

■ the Dialog Manager (described in Inside Macintosh, Volumes IV, V) 

■ the Control Manager (described in Inside Macintosh, Volumes I, IV, V) 

■ the Resource Manager (described in Inside Macintosh, Volumes I, IV, V) 
To use the network look-up utilities, you need to be familiar with 

■ AppleTalk (described in Inside Macintosh, Volumes II, V) 
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Communications Toolbox utilities 


This section explains the routines and data structures that make up the Communications 
Toolbox utilities. Your application can not call these routines from interrupt level. 

Below is a listing of the routines described in this section in the order in which they are 
presented. 

InitCTBUtilities / 192 
CTBGetCTBVersion / 192 
NewControl / 193 
AppendDITL / 198 


CountDITL / 201 
ShortenDITL / 201 
NuLookup / 203 
NuPLookup / 204 
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InitCTBUtilities 


Initializing the Communications Toolbox utilities 

InitCTBUtilities initializes the Communications Toolbox utilities. 

A Warning Your application must call this routine after calling the standard Macintosh 


Function 

Toolbox initialization routines and the Communications Resource Manager initialization 
routine (initCRM); your application can then call other Communications Toolbox 
manager initialization routines. All code that uses any Communications Toolbox routines 
mttf^call this routine once and only once, a 

InitCTBUtilities : CTBUErr; 

Description 

InitCTBUtilities retums an Operating system error code if appropriate. Valid 
values are: 

TYPE 

CTBUErr = OSErr; 

CONST 

ctbuGenericError = -1; 

ctbuNoErr = 0; 

Your application must check for the presence of the Communications Toolbox before 
calling this function. Sample code under “Determining Whether the Managers are 

Installed” in Appendix B shows you how your application can make this check. 


CTBGet CTBVe rsion 


Getting the Communications Toolbox version number 

CTBGetCTBVersion returns the version number of the Communications Toolbox 



utilities. 

Function 

CTBGetCTBVersion: INTEGER; 

Description 

The Communications Toolbox version described in this document is: 

CONST 

curCTBUVersion = 1; 
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NewControl 


Pop-up menu control definition procedure 

The Communications Toolbox includes a control definition procedure (' cdef ') that 
extends the function of PopUpMenuSeiect, which is a part of the Menu Manager in 
the Macintosh Toolbox. This ' cdef •, with resource ID=63, is available on Macintosh 
computers running with the Communications Toolbox installed. 

Your application creates a pop-up menu the same way that it would create any other 
Macintosh control. Figure 7-1 shows a pop-up menu control in its inactive and active 
states. 

■ Figure 7-1 Pop-up menu in its inactive and active states 
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Function NewControl (theWindow: WindowPtr; boundsRect: Rect; 

title:STR255; visible: BOOLEAN; value: INTEGER; min,max: 
INTEGER; procID: INTEGER; refCon: LONGINT): ControlHandle; 

Description value specifies the manner in which the title of the pop-up menu is to be justified and 

drawn, value is a bit field with the following masks: 

CONST 


popupTitleBold 


$0100; 

popupTitleltalic 

= 

$0200; 

popupTitleUnderline 

= 

$0400; 

popupTitleOutline 


$0800; 

popupTitleShadow 

= 

$1000; 

popupTitleCondense 

= 

$2000; 

popupTitleExtend 

= 

$4000; 

popupTitleNoStyle 

= 

$8000; 

popupTitleLeftJust 

= 

$0000; 

popupTitleCenterJust 

= 

$0001; 

popupTitleRightJust 

= 

$00FF; 
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To have the pop-up menu draw the title of the control with more than one of the 
characteristics listed above, pass in value the sum of all desired characteristics. 

Once a pop-up menu has been created, the pop-up menu 'cdef' sets value to 
its minimum valid value. Your application can then use the value of the control to 
determine the currently selected item. 

min represents the resource ID of the menu in the pop-up control when the control is 
being created. After the control has been created, the pop-up menu ' cdef ' sets the 
minimum value of the control to 1. 

max contains the width of the pop-up tide area when the control is being created. After 
the control has been created, the pop-up menu ' cdef ' sets the maximum value of the 
control to the number of items in the pop-up menu. 

prociD should be an integer equal to popupMenuCDEFproc plus the appropriate 
variation code. popupMenuCDEFproc is a constant set by Apple Computer and is equal 
to 1008 (63 times 16). Variation codes are discussed later in “About Variation Codes.” 

If the pop-up menu is created using the popupUseAddResMenu variation code, the 
pop-up menu 'cdef' creates the control and then calls AddResMenu to add items 
to the menu associated with the pop-up menu control. The value in ref con is typecast 
to the type ResType, which is used by the routine AddResMenu. 

For example, if ref Con is longint ('font '), the pop-up menu control appends 
a list of the fonts installed in the system to the menu associated with the pop-up menu 
control. 

After the control has been created, your application can use the control’s ref Con 
field for whatever purpose it requires. 

About variation codes 

Your application can specify variation codes when it passes a value in prociD . Variation 
codes alter the characteristics of the pop-up menu control. To specify the appropriate 
variation code, your application sums the values that correspond to the desired pop-up 
menu characteristics with the basic pop-up menu constant popupMenuCDEFproc. 
Valid values are shown next. 
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Variation code constant Description 


popupFixedWidth 


popupUseCQD 


popupU s eAddRe sMenu 


popupUseWFont 


This constant specifies constant control width. If your 
application specifies this value, the pop-up menu ' cdef • will 
not resize the control horizontally to fit long menu items. The 
width of the pop-up box where the currently selected item is 
drawn equals the width of the control, minus the width of the 
pop-up title your application specifies when it creates the 
control. If the contents of the pop-up box do not fit into the 
space provided, the contents is trunated to fit and ellipses (...) 
are appended to its end. If this variation code is not specified, 
the contents of the pop-up box are guaranteed to fit, because 
the pop-up menu ' cdef • resizes the control horizontally. 

This constant specifies the use of Color QuickDraw. If your 
application specifies this value, the pop-up menu ' cdef ' 
uses the colors stored in the menu color table (' mctb ') for the 
color of the pop-up box when Color QuickDraw is available. If 
Color QuickDraw is unavailable, this variation code is ignored. 

If the grafPort that owns the control is an old-style (classic 
QuickDraw) grafPort, the pop-up menu control attempts to 
create a cGrafPort to draw the pop-up menu control in the 
correct colors and then dispose of it when finished drawing. By 
using a cGrafPort, the control avoids the distortion that occurs 
when converting Color QuickDraw colors to classic QuickDraw 
colors. 

If your application specifies this value, the pop-up menu 
'CDEF' treats the refCon field as a ResType, and 
performs an AddResMenu with this resource type on the 
menu. If the control is being created with the NewControi 
routine, the pop-up menu 'cdef' receives ref Con from 
your application. If the control is being created with 
GetNewControi, the pop-up menu 'CDEF' receives 
ref Con from the control template (resource type ' cntl '). 


If your application specifies this value, the pop-up menu 
' CDEF ' draws the pop-up menu control using the font and 
size of the grafPort that owns the control. The pop-up menu, 
when active, also uses the font and size specified by the 
grafPort, instead of using the standard system font. 
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The values that correspond to the variation code constants are as follows: 

CONST 


$ 0001 ; 

$ 0002 ; 

$0004; 

$0008; 


popupFixedWidth 
popupUseCQD 
popupU s eAddRe sMenu 
popupUseWFont 


After the pop-up control has been created 

After NewControi creates the pop-up menu, min contains 1, max contains the 
number of items in the menu that is associated with the control, and ref con becomes 
available for the application to use. 

In the process of creating the new control, NewControi may modify 
boundsRect to reflect the actual width of the pop-up menu box. 

Your application can get the currently selected menu item by calling cetctivalue. 

Other pop-up menu control characteristics 

There are three pop-up menu control characteristics that you need to be familiar with: 
how the utility changes the width of the control, how the control changes with regard to 
system justification, and how your application can access the menu handle. 

Whenever the pop-up control is redrawn, the utility calls CaicMenuSize . This 
routine recalculates the size of the menu associated with the control, to allow for the 
addition of new items in the menu. The pop-up menu ' cdef ' also updates the width 
of the pop-up menu control to the sum of the width of the pop-up title, the width of 
the longest item in the menu (the menuwidth field of the menu information record), 
and some aesthetic white space. As previously desaibed, your application can override 
this characteristic by using the variation code popupFixedwidth. 

When the system justification is te JustRight, the pop-up control looks like the 
pop-up menu control shown in Figure 1-2. 

■ Figure 7-2 Pop-up menu control when system justification is teJustRight 
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Note that the positions of the pop-up box and the pop-up title are reversed from the 
standard positions shown in Figure 7-1. 

Your application obtains the menu handle and the menu ID for the menu associated 
with the pop-up control by dereferencing the contriData field of the control record. 
The contriData field is a handle to a block of private information. The first four 
bytes of this block are the menu handle; the next two bytes are the menu ID for the 
menu associated with the control. The format of the popupPrivateData structure 
is as follows; 

TYPE 

popupPrivateData = RECORD 


mHandle 

mID 

mPrivate 


MenuHandle; 

INTEGER; 

ARRAY[0..0] OF SignedByte 


END 
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Manipulating dialog item lists (DITLs) 

As a logical extension to the Dialog Manager routines in the Macintosh Toolbox, the Communications 
Toolbox provides three procedures to append, shorten, and count the number of items in dialog item lists. 
You can use these routines regardless of whether or not your program provides communications services. 


AppendDITL 

Appending to a dialog item list 

AppendDITL lets your application append dialog items to an exisiting dialog box. 


Procedure AppendDITL(theDialog: DialogPtr; theDITL: Handle; method: 

DITLMethod) ; 


Description theDialog is a pointer to the dialog box in which you want to append an item list. 

theDITL is a handle to the item list that you want to append. 

method specifies the manner in which you want the items in the new item list to be 
appended: overlay, right, or bottom. Here are the acceptable vaules for method, followed 
by examples of the results of each method; 

TYPE 

DITLMethod = INTEGER 

CONST 

overlayDITL = 0; 

appendDITLRight = 1; 

appendDITLBottom = 2; 

Figure 7-5 shows the initial dialog box, containing items 1 and 2, and the items to be 
appended, namely items 3 and 4. 


Figure 7-3 Initial dialog box and to-be-appended items 


( 0 , 0 ) 


/ 



( 0 , 0 )" 



Initial dialog box 


To-be-appended items 


If your application uses overlayDITL, AppendDITL superimposes the items in 
the to-be-appended dialog item list onto the dialog item list associated with 
theDialog, as shown in Figure 7-4. 
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Figure 7-4 Dialog box after appended items are superimposed 
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If your application uses appendDiTLRight, AppendDiTL offsets the items in 
the to-be-appended dialog item list by the upper-right coordinate of 
theDiaiog^. portRect, as shown in FjgMtB 7-5. Then AppendDiTL appends the 
list to the end of the dialog item list associated with theoiaiog. AppendDiTL 
automatically expands the dialog box as needed. 


■ Figure 7-5 Dialog box after items are appended to the right 
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If your application uses appendDiTLBottom, AppendDiTL offsets the items in 
the to-be-appended dialog item list by the lower-left coordinate of 
theDiaiog''. portRect , as shown in Figure 7-6. Then, AppendDiTL appends the 
list to the end of the dialog item list associated with theDiaiog, and expands the 
dialog box as needed. 

■ Figure 7-6 Dialog box after items are appended to the bottom 
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If you know your application will need to restore a window to the size it was before 
an AppendDiTL routine, your application should save that size before it calls 
AppendDiTL. shortenDiTL, the procedure that shortens dialog item lists, will not 
automatically resize the dialog box. (shortenoiTL is described later in this chapter.) 

Because AppendDiTL modifies the contents of theDiTL, your application must 
get rid of the dialog item list after calling AppendDiTL. Here is a typical calling sequence; 

theDITL ;= GetResource(*DITL*, thelD); 

AppendDiTL(theDialog, theDiTL, appendDITLBottom); 

ReleaseResource(theDiTL); 

special ways to append items 

Your application can append a new dialog item list relative to the location of specific items 
in the dialog box, rather then appending new dialog items relative to the coordinates of 
Dialog''. portRect. To append a dialog item list in this way, your application uses a 
negative number in the method parameter. This number corresponds to the item that is 
the point of reference. For instance, if method is -2, then the items in the to-be-appended 
dialog item list have their item boxes offset by the upper-left corner of the item box for 
item 2 in theDialog. Figure 7-7shows how item 3 and item 4 were appended relative to 
the position of item 2. Item 3, because it was appended relative to the topLef t of item 
2, appears on top of item 2. 

■ Figure 7-7 Dialog box after items are appended relative to item 2 
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CountDITL 


Counting the number of items in a list 

CountDITL retums the number of items in the dialog item list associated with 


Function 

theDialog. 

CountDITL(theDialog:DialogPtr): INTEGER; 

ShortenDiTL 



Shortening a dialog item list 

shortenDiTL removes items from the end of the given dialog item list, but does not 



automatically resize the dialog box. If you know that your application will need to resize 
the dialog box, save the size before calling AppendoiTL and use the Window Manager 
routine SizeWindow. 

Procedure 

ShortenDiTL(theDialog: DialogPtr; numberItems: INTEGER); 

Description 

theDialog specifies the dialog box to be shortened. 

numberitems specifies the number of items to be removed. 
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Showing AppleTalk entities: NuLookup and NuPLookup 

The network look-up utilities, NuLookup and NuPLookup, allow your application to present the 
user with a dialog box containing AppleTalk entities. By providing either NuLookup or 
NuPLookup with the proper parameters, your application can include in the dialog box one or more 
types of AppleTalk entities. Both NuLookup and NuPLookup perform much the same task, 
but NuPLookup gives you a bit more flexibility. 

The results of NuLookup and NuPLookup are displayed in a dialog box similar to the one in 
Figure 7-8, which shows the results of a search for LaserWriter® printers in the zone “Blackcap 
Basin.” 


■ F^;ure7-8 Network look-up dialog box 
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NuLookup and NuPLookup also provide your application with the option of using filter 
routines or hook procedures to customize the dialog box or to filter out information that would 
otherwise be included in it. These routines are described later in this chapter, in “Hook and Filter 
Procedures.” 

In the network look-up dialog box, pressing the Return key has the same effect as pressing the 
OK button. Holding down the Command key and pressing the Period key has the same effect as 
clicking Cancel. The Up Arrow key and the Down Arrow key change the selected name to either the 
cell above or the cell below. Holding down the Command key while pressing the Up Arrow key or 
the Down Arrow key moves the selected zone up or down one cell. 
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NuLookup 


Network lookup 

NuLookup returns to your application the object/type/zone tuple and AppleTalk 
node/network/zone numbers tuple for the item that the user selected. 

When your application first calls NuLookup , this routine builds a zone list (if possible). 
Then NuLookup makes a synchronous Name Binding Protocol (NBP) lookup for the 
specified objects. Next, NuLookup builds the preliminary object list and presents the 
dialog box to the user. At all times while the dialog box is displayed, NuLookup 
continues an asynchronous NBP lookup with long retry and timeout. It ages objects in 
the name list so that if an object misses several consecutive asynchronous NBP lookups, 
it is removed from the list. Items that appear in subsequent NBP lookups are added to 
the list if they were not already in the lookup list. 

Both the zone and name lists are alphabetized by using the international utilities. 

Function NuLookup(where: Point; prompt: STR255; numTypes: INTEGER; 

typeList: NLType; nameFilter: ProcPtr; zoneFilter: ProcPtr; 
hookProc: ProcPtr; VAR theReply: LookupReply): INTEGER; 

Description where indicates in global coordinates where NuLookup should place the upper-left 

comer of the look-up dialog box. 

prompt is a string displayed at the top of the look-up dialog box. In Figure 7-8, the 
string “Looking for LaserWriter” was passed to NuLookup. 

numTypes is the number of object types that will be included in the lookup. If 
numTypes is-1, NuLookup searches for all object types. 

typeList is a Structure of type NLType, which is an array of AppleTalk object types, 
along with a handle to an icon. If no icon is required, pass nil for hicon. 


TYPE 

NLTypeEntry 

RECORD 

hicon : 

Handle; 

typeStr 

Str32; 

END; 

NLType = 

Array[0..3]of NLTypeEntry; 


♦ Assembly note: Using assembly language, you can specify more than four object 
types by passing a pointer to an array with the required number of items. 
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nameFilter is a pointer to a procedure that filters out object/type/zone tuples from 
the network look-up dialog box. zoneFiiter is a pointer to a procedure that filters 
out zones from the network look-up dialog box. hookProc is a pointer to a hook 
procedure that modifies the behavior of items in the dialog box or calls a background 
procedure. These three procedures are described later in this chapter, in “Hook and Filter 
Procedures.” If you do not need these routines in your application, specify nil. 

theRepiy is the look-up reply record that contains the object/type/zone tuple for the 
object, if any, that was selected by the user. The record also contains the AppleTalk 
address consisting of node/network/zone numbers. 

TYPE 

LookupReply 

theEntity 
theAddr 

END; 

When your application initially passes the theRepiy data structure into the 
NuLookup procedure, theRepiy. theEntity should contain the default zone and 
name. If the specified object is not in the list of accepted objects in typeLi st , the 
specified object is ignored, and only the default zone is set. If an appropriate match is 
found in the initial lookup, the specified zone and the specified name of the given object 
are selected when the dialog box comes up. 

NuLookup returns one of three values: 

CONST 


nlOk 

= 

0; 

nlCancel 

= 

1; 

nlEject 

= 

2; 


nlok is returned if the user clicks the OK button in the dialog box. nicancei is 
returned if the user clicks the Cancel button. nlE j ect is returned if the dialog box 
stops because of the hook procedure. 


RECORD 

EntityName; 

AddrBlock; 


NriP Lookup 

A more versatile network lookup 

NuPLookup performs much the same task as NuLookup, except that it gives 
programmers even greater control over customization of the network look-up dialog box. 
Additional parameters that can be specified are userData, diaiogiD, and 
f ilterProc. 

Function NuPLookup(where: Point; prompt: STR255; numTypes: INTEGER; 

typeList: NLType; nameFilter: ProcPtr; zoneFiiter: ProcPtr; 
hookProc: ProcPtr; userData: LONGINT; dialogID: INTEGER; 
filterProc: ProcPtr; VAR theRepiy: LookupReply): INTEGER; 
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userData is a field that the user can specify. It may be referenced from the hook 
procedure or the filter procedure with the ref Con field of the dialog box record. 
refCon is a handle to the useroata value. 

The following code fragment demonstrates how to access the userOata field: 

TYPE 

LongH = "^LongPtr; 

LongPtr = '"LONGINT; 

BEGIN 

myUserData := LongH (GetWRefCon (theDialog) ) 

END; 

diaiogiD is the resource ID for a dialog box (and for the corresponding dialog item list) 
that is to replace the standard look-up dialog box. All of the items in the replacement 
dialog item list must correspond to items in the standard dialog item list, although they 
can be moved around. Table 7-1 lists standard items and their placement. 


■ Table 7-1 TMAddSearch search-area delimiters 


Item number 

Type 

Rectangle (top, left, bottom, right) 

1 

OK button 

{172,240,192,3101 

2 

Cancel button 

(172,320,192,3901 

3 

Default highlight (useritem) 

(168,236,196,3141 

4 

Title (staticText) 

(5,15,21,2101 

5 

Item list (userltem) 

(25,15.189,2101 

6 

Zone list title (staticText) 

(5,240,21,3911 

7 

Zone list (userltem) 

(25,240,147,3911 

8 

Line (userltem) 

(25,225,193,2261 

9 

Version (userltem) 

(197,360,207,4001 

10-13 

Reserved 



filterProc is a modal dialog box filter procedure that NuPLookup calls after the 
standard NuLookup modal dialog box filter procedure. The format of the filter 
procedure is the same as that of a standard modal dialog box filter procedure. See 
Chapter 13 of Inside Macintosh, Volume I for more information about modal dialog 
filter procedures. 
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Hook and filter procedures 

You can customize the operation of the network look-up dialog box for specific 
applications by using the filter procedures and the hook procedure. Filter procedures are 
used to filter out zones from inclusion in the zone list, or to filter out objects from the 
object list. The hook procedure is used to modify the behavior of items in the dialog box, 
and can also be used to call a background procedure. 


MyNameFliter 

Name filters 


Before each item name is included in the network look-up dialog list, the item is passed to 
the name filter procedure for processing. Specify nil if there is no filter procedure. 

Function MyNameFilter(theEntity: EntityName): INTEGER; 

Description This filter procedure is passed the network entity in theEntity, and returns an integer 

with one of the following values; 

CONST 


nameinciude = 

1; 

nameDisable = 

2; 

nameReject = 

3; 


nameinciude results in the inclusion of theEntity in the name list of the 
network look-up dialog box. nameoisabie results in the inclusion of theEntity 
but disables it; the item in the list is visible but dimmed, and cannot be selected. 
nameReject causes theEntity not to appear in the list. 
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MyZoneFilter 


Zone filters 


Function 

Before each zone item is included in the network look-up dialog list, the item is passed to 
the zone filter procedure for processing. Specify nil if there is no filter procedure. 

MyZoneFilter(theZone: STR32): INTEGER; 

Description 

NuLookup and NuPLookup pass the name of an AppleTalk zone in theZone to the 
zone filter procedure, which returns an integer with one of the following values: 

CONST 

zoneinclude = 1; 

zoneDisable = 2; 

zoneReject = 3; 

zoneinclude results in the inclusion of theZone in the zone list in the network 
look-up dialog box, zoneDisable results in the inclusion of theZone but disables 
it; the item in the zone list is visible, but dimmed, and cannot be selected. zoneReject 
causes theZone not to appear in the Zone list. 
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MyHookProc 


The hook procedure 

NuLookup and NuPLookup call MyHookProc immediately after ModalDialog 
and before the standard hook procedure. ModalDialog returns a number that 
corresponds to the item clicked in the dialog box. NuLookup and NuPLookup employ 
a modal dialog box filter procedure that returns the item number for any physical items 
clicked in the dialog box, as well as the item numbers of any fake item clicked. 

Function MyHookProc(item; INTEGER; theDialog: DialogPtr): INTEGER; 

Appropriate fake and real dialog box items are as follows: 

CONST 


real items in the 

dialog 

item list 

hookOK 

= 

1; 

hookCancel 

= 

2; 

hookOutline 


3; 

hookTitle 

= 

4; 

hookItemList 

= 

5; 

hookZoneTitle 

= 

6; 

hookZoneList 

= 

7; 

hookLine 

= 

8; 

hookVersion 

= 

9; 

hookReservedl 

= 

10; 

hookReserved2 

= 

11; 

hookReservedS 

= 

12; 

hookReserved4 

= 

13; 

fake items in dialog item list 

hookNuii 

= 

100; 

hookitemRefresh 

= 

101; 

hookZoneRefresh 

= 

102; 

hookEject 

= 

103; 

hookPreflight 

= 

104; 

hookPostflight 

= 

105; 

hookKeyBase 

= 

1000; 


The first 13 items correspond to physical items in the dialog item list. The other items 
are fake items that correspond to certain actions that may need to be performed. 

hookNuii is a fake event that corresponds to a null event. The standard modal 
dialog box filter procedure returns hookNuii in itemHit for null events. 

hookitemRef resh causes the item list in the look-up dialog box to be discarded 
and regenerated. 

hookZoneRef resh causes the Zone list in the look-up dialog box to be discarded 
and regenerated. This value also causes a hookitemRef resh event to be generated. 

hookEject causes all outstanding NBP lookups to be terminated and nLEject 
to be returned by NuLookup. 
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hookPref light is processed after the zone and object lists are formed, but before 
the dialog box is displayed. 

hookPostf light is processed before the dialog box is disposed of. 

Any item greater than hookKeyBase is actually the ASCII value of the key that is 
pressed, offset by hookKeyBase. For example, an itemHit of 1032 decimal would 
correspond to a keyOown event generating a space (ASCII 32 decimal). 


Chapter 7: Macintosh Communications Toolbox Utilities 


209 




cmSsetupMsg 

Your setup-definition code resource should perform a function similar to that shown in the 
example code when it receives cmSsetupMsg from the Connection Manager. 

When passed to your connection tool, p3 will be a pointer to magiccookie, which is a 

LONGINT. 

PROCEDURE Setup(pSetup: CMSetupPtr); 

CONST 

myFirstItem = 1; 
mySecondItem = 2; 

VAR 

first; INTEGER; { first item appended (0-based) } 

pConfig;ConfigPtr; 


BEGIN 

WITH pSetup^ DO 
BEGIN 

first := count - 1; { count is 1-based } 

pConfig ;= ConfigPtr(theConfig); { get the config ptr } 

GetDItem(theDialog, first+myFirstItem, itemKind, itemHandle, 
itemRect); 

SetCtlValue (ControlHandle (itemHandle) , pConf ig'^. foobar) ; 

GetDItem(theDialog, first+mySecondItem, itemKind, itemHandle, 
itemRect); 

SetCtlValue (ControlHandle (itemHandle) , 1-pConfig'^. foobar) ; 
END; {with} 

END; 


cmSitemMsg 

Your setup definition code resource should perform a function similar to that shown in the example 
code when it receives cmSitemMsg from the Connection Manager. 

When passed to your connection tool, pi points to an item that was selected from the dialog 
item list, and p3 contains a pointer to magicCookie. Your tool can change the selected item by 
modifying the item number to which pi points. 
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PROCEDURE Item(pSetup: CMSetupPtr; pitem: IntPtr); 
CONST 

myFirstItem = i; 

mySecondItem = 2; 


VAR 


first 

: INTEGER; 

pConfig 

: ConfigPtr; 

value 

: INTEGER; 

BEGIN 


WITH pSetup^ DO 


BEGIN 


first := 

count - 1; 

pConfig : 

:= ConfigPtr(theConfig) 


{ first item appended (0-based) } 


{ count is 1-based } 

{ get the config ptr } 


CASE pltem'^-f irst OF 
myFirstItem: 

BEGIN 

GetDItem(theDialog,first+myFirstItem,itemKind, 
itemHandle,itemRect); 

value := GetCtlValue(ControlHandle(itemHandle)) 
value := 1 - value; 

pConfig'^. foobar := value; { stick into config record } 

SetCtlValue(ControlHandle(itemHandle), value); { update control } 
END; 

mySecondItem: 

BEGIN 

SysBeep (5); 

FlashMenuBar(0); 

END; 

END; { case } 

END; { with } 

END; 


cmSfllterMsg 

Your setup definition code resource should perform a function similar to that shown in the example 
code when it receives cmsfiiterMsg from the Connection Manager, 

When passed to your connection tool, pi will contain a pointer to an event record, p 2 will 
contain a pointer to an item clicked in the dialog list, and p3 will contain a pointer to 
magicCookie. 

If the event that was passed to this function was handled, your connection tool should return 1; 
otherwise, it should return 0. 
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cmMsetMsg 

Your tool will receive cmMsetMsg from the Connection Manager when the application requires 
your tool to set the fields of the connection record to values that are specified in a string. The 
Connection Manager will pass a pointer to this string as a parameter to this call. The sample code 
shows how your tool can handle cmMsetMsg. 

When passed to your connection tool’s scripting interface code resource, pi will be a pointer to 
an American English null-terminated string that contains tokens representing a configuration record. 

Your tool should return one of the following values: a number less than -1 to indicate an 
osEr r , -1 to indicate a generic error, 0 if there was no problem with the string, or a positive number 
to indicate the character position where parsing was stopped. 

The Connection Manager automatically calls cMvaiidate after your tool has responded to 
cmMsetMsg. 

FUNCTION SetConfig(hConn: ConnHandle; theSource: Ptr) : INTEGER; 

VAR 

pConfig : ConfigPtr; 

paramStr, 

valueStr : Str255; 

outOfTokens : BOOLEAN; 

returnVal : INTEGER; 

BEGIN 

{ Init some stuff } 
pConfig := ConfigPtr(hConn^^.config) ; 
returnVal := noErr; 

IF (theSource^ = CHR(O)) THEN 
outOfTokens := TRUE 

ELSE 

outOfTokens := FALSE; 

WHILE NOT outOfTokens DO BEGIN 

(* Build the first token and put it into paramStr *) 

IF (paramStr = 'FOOBAR') THEN BEGIN 

(* Build the next token and put it into valueStr *) 

pConfig^.foobar := valueStr; 

END 

ELSE BEGIN 

(* returnVal = location of the paramStr *) 

LEAVER- 

END; 


{ tool specific config record } 

{ param and value strings } 

{ end of the line? } 

{ what to return } 


(* index to next token *) 
END; { while } 

SetConfig := returnVal; 

END; 
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The localization code resource 

Your connection tool’s localization code resource is responsible for providing the services necessary 
to localize your tool. It must handle two messages, cmLZEngiish and cmLZinti. 

Your localization code resource should be a resource of type ■ cioc '. It should be able to 
handle the parameters shown in the example code. 

FUNCTION cloc(hConn: ConnHandle; msg: INTEGER; pi, p2, p3: LONGINT) : LONGINT 

Valid values for msg are as follows: 

CONST 

cmL2English = 0; 

cmL2Intl = 1; 

For each of the messages defined here, pi, p 2 , and p3 take on different meanings. These 
meanings are discussed in the message descriptions that follow. 

cmL2English and cmL2Intl 

Your tool will receive cmL2Engiish from the Connection Manager when the application requires 
your tool to localize a string to English. When the parameters pi, p 2 , and p3 are passed to your 
tool, pi will contain a pointer to a localized null-terminated string that contains tokens 
representing a configuration record; p2 will contain a pointer that points to a second pointer. 

Your tool will have to allocate space for this pointer (by calling NewPtr), which contains the 
American English null-terminated configuration string. p3 will contain a language identifier, which 
is defined in the discussion of the Script Manager in Inside Macintosh, Volume V. 

Your tool will receive cmL2inti from the Connection Manager when the application requires 
your tool to localize a string to a language other than English. When the parameters pi, p 2 , and 
p3 are passed to your tool, pi will contain a pointer to an American English null-terminated 
string that contains tokens representing a configuration record; p 2 will contain a pointer to a 
second pointer. Your tool will have to allocate space for this pointer, which contains the localized 
configuration string. p3 will contain a language identifier, which is defined in the Script Manager 
in Inside Macint(xh, Volume V. The next code example shows how your tool can handle both 
cmL2English and cmL2lntl. 

After executing the code necessary to respond to cmL2Engiish or cmLZinti, your 
routine should return nil if there was a Memory Manager error or if the language requested is not 
available. It should also return any appropriate error code in the status field of the connection 
record. 

{ main entry point for cloc resource } 

FUNCTION cloc(hConn: ConnHandle; msg: INTEGER; pi, p2, p3: LONGINT): LONGINT; 

TYPE 

PtrPtr = '"Ptr; 

VAR 

outPtr: Ptr; 
procID: INTEGER; 
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begin 


outPtr := PtrPtr (p2) 
case msg of 

cmL2English; 
cloc 

cmL2Intl; 


{ get output pointer } 


Translate ( Ptr (pi), outPtr,p3,verUS); 


cloc := Translate ( Ptr(pi),outPtr,verUS,p3); 


end; {case} 

PtrPtr(p2)'^ := outPtr; 


{ return output pointer } 


end; { mytscrDEF } 

{ Translates an input config string from one language to another } 
{ returns 0 if no problem, non zero if there is a problem } 

{ This routine needs to allocate outputStr. } 

{ if language is not supported, return 0 but leave outputStr NIL } 

function Translate( inputStr: Ptr; var outputStr: Ptr; 

fromLanguage,toLanguage: longint): longint; 

BEGIN 

end; { Translate } 


config: the configuration record 

An application using your tool may save and restore the contents of a configuration to set the 
state of the connection at any time. The configuration record, therefore, should be self-contained 
and should not contain any pointers or handles to other data structures. Your tool allocates this 
record in response to cmoefauitMsg. The Connection Manager, not the tool, deallocates the 
configuration record when the application calls CMOispose. 
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Quick reference 

This section contains reference information for the data structures, definition procedures, and 
resource types that you need to write a terminal tool. A table at the end of this section lists 
messages the Connection Manager sends to connection tools, and what is passed in the parameters 
with each message. 


Data structures 

TYPE 

CMSetupPtr 

CMSetupStruct 

theDialog 
count 
theConfig 
procID 

END; 


'^CMSetupStruct; 
RECORD 
DialogPtr/ 
INTEGER; 

Ptr; 

: INTEGER 


Definition procedures 


FUNCTION 

cdef(hConn; 

ConnHandle; 

msg: 

INTEGER; 

pi/ 

P2/ 

P3: 

LONGINT) 

: LONGINT; 

FUNCTION 

cval(hConn: 

ConnHandle; 

msg: 

INTEGER; 

pi/ 

P2/ 

P3: 

LONGINT) 

: LONGINT; 

FUNCTION 

cset(pSetup: 

CMSetupPtr; 

msg: 

INTEGER; 

pi/ 

P2/ 

P3: 

LONGINT) 

: LONGINT; 

FUNCTION 

cscr(hConn: 

ConnHandle; 

msg: 

INTEGER; 

pi/ 

P2/ 

p3: 

LONGINT) 

: LONGINT; 

FUNCTION 

cloc(hConn: 

ConnHandle; 

msg: 

INTEGER; 

pi/ 

P2/ 

P3: 

LONGINT) 

: LONGINT; 


Resource types 

type 'cbnd* { 

integer = $$CountOf(TypeArray) - 1; 
array TypeArray { 

literal longint; /* Type */ 

integer = $$CountOf(IDArray) - 1; 
wide array IDArray { 

integer; /* Local ID */ 

integer; /* Actual ID */ 

}; 

}; 
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Table 8-1 Connection Manager messages and parameters 
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Chapter 9 Writing Connection Tools 




























THIS CHAPTER tells you how to write the main code resource for a 
connection tool. There are at least five other code resources that you need to 
include as part of your tool; they are described in Chapter 8 . You should read 
that chapter, as well as Chapter 3 , before reading this chapter. 

This chapter describes all the messages, parameters, and data structures that 
the Connection Manager passes to your tool’s main code resource. Also in this 
chapter is sample code (with pseudocode mixed in) that will help you 
understand what your tool should do when it receives any of the messages. A 
quick reference at the end of the chapter shows you what you should name 
your six connection tool resources. It also lists the messages the Connection 
Manager sends to your tool, and the parameters that the Connection Manager 
passes with each message. 
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Your connection tool’s main code resource 

The purpose of the main code resource is to parse messages from the Connection Manager and then 
to branch to a routine that can handle each message. The main code resource should be a resource of 
type ' cdef ' and should be able to accept the parameters shown here. 

FUNCTION cdef(hConn: ConnHandle; msg: INTEGER; pi, p2, p3: LONGINT) : LONGINT 

The messages accepted by the main code resource, and their associated values, are as follows: 

CONST 


cmlnitMsg 


0; 

cmDisposeMsg 

= 

1/ 

cmSuspendMsg 

= 

2; 

cmResumeMsg 


3; 

cmMenuMsg 

= 

4; 

cmEventMsg 

= 

5; 

cmActivateMsg 

= 

6; 

cmDeactivateMsg 

ss 

7; 

cmIdleMsg 

= 

50; 

cmResetMsg 

= 

51/ 

cmAbortMsg 

= 

52; 

cmReadMsg 


100 

cmWriteMsg 

= 

101 

cmStatusMsg 


102 

cmListenMsg 

= 

103 

cmAcceptMsg 

=s 

104 

cmCloseMsg 

= 

105 

cmOpenMsg 

= 

106 

cmBreakMsg 

= 

107 

cmlOKillMsg 

= 

108 

cmEnvironsMsg 

= 

109 


For each of the messages defined here, the three parameters ' cdef ■ returns, namely pi, p 2 , 
and p3, take on different meanings. These parameters are described in the message descriptions 
that follow. Your tool can return an appropriate operating-system error code, or 
cmNotsupported if it does not undertand the message it received. 

cmResetMsg 

The Connection Manager will send cmResetMsg to your tool when the application requires your 
tool to reset the connection. The specific state to which your tool should reset the connection 
depends upon the connection protocol. 
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cmMenuMsg 

The Connection Manager will send cmMenuMsg to your tool when a menu event has occurred 
in the application. When passed to your tool, pi will contain the menu ID, and p2 will contain 
the menu item. 

The sample code shows you a basic template into which you can code your tool’s response to 
cmMenuMsg. When done, your tool should pass back 0 if the menu event was not handled, and 1 if 
it was. 

FUNCTION myMenu(hConn : ConnHandle; mID : INTEGER; mitem: INTEGER) ; LONGINT; 
BEGIN 

myMenu := 0; 

{ if mine then 
begin 

myMenu := 1; 

Process the menu command. 

end; 

} 


END; 


cmListenMsg 

An application will call the CMListen routine when it requires your tool to wait for an incoming 
connection request. When passed to your tool, pi will contain the address of 
CMCompietorRecord, and p2 will Contain the timeout value in ticks. 

Your tool uses a CMCompietorRecord Structure when it receives a message to process 
asynchronously. This record contains a pointer to a completion routine your tool calls upon 
completion of the specified operation. 

If the operation is to be performed asynchronously, the async field of the 
CMCompietorRecord is TRUE and the pointer to the Completion routine is in the 
compietionRoutine field. If the operation is to be performed synchronously, the async 
field of the CMCompietorRecord is FALSE. Your tool should ignore the 
compietionRoutine field in this case. 

The CMCompietorRecord is Created in a local stack frame by the Connection Manager; 
therefore, your tool should copy the contents of the CMCompietorRecrd data structure if any 
information in it will be needed later. 

TYPE 

CMCompletorPtr 
CMCompietorRecord 
async 

compietionRoutine 

END; 

The sample code shows you a basic template into which you can code your tool’s response to 
cmListenMsg. When done, your tool should pass back an appropriate error code. 


'"CMCompietorRecord; 

RECORD 

BOOLEAN; 

ProcPtr; 


236 Macintosh Communications Toolbox Reference 




FUNCTION 

BEGIN 


myListen(hConn : ConnHandle; completor 
timeout : LONGINT) : CMErr; 


CMCompletorPtr; 


{ If connection is already open, return error condition } 

{ Establish physical layer driver } 

{ If completor'^. async then 
begin 

Do async listen call. 

Set listen pending flag. 

Issue VBL task to terminate listen in specified timeout. 

end 

else 


END; 


Do sync listen call and return error when timeout. 


cmIdleMsg 

Your tool will receive cmidieMsg when the application has idle time, such as when it needs your 
tool to check the status of an asynchronous routine. An application can not call cMidie from 
interrupt level. 

cmEventMsg 

The Connection Manager will pass cmEventMsg to your tool when an event occurred in a 
window associated with the connection tool. The sample code shows a template into which you 
can code your tool’s response to cmEventMsg. 

When passed to your tool, pi will be a pointer to the event record. The reference constant 
field of the window record will contain the connection handle. 

PROCEDURE myEvent(hConn : ConnHandle; theEvent : EventRecord); 

CONST 

CancelButton = 2; 

VAR 

theDialog : DialogPtr; 

theltem : INTEGER; 


BEGIN 

{ Check if it is a dialog related event } 

if IsDialogEvent(theEvent) then 

begin 

{ get the item hit } 

if DialogSelect(theEvent,theDialog,theltem) then 
begin 

if theltem = CancelButton then 
{ Cancel the connection } 

end; 

end 

else 

{ Handle the keyDown, updateEvt, mouseDown and any other event here } 

END; 
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cmAbortMsg 

The Connection Manager will pass cmAbortMsg to your tool when the application has requested 
that a pending open or listen be aborted. The sample code shows a template into which you can 
code your tool’s response to cmAbortMsg. 

PROCEDURE myAbort(hConn ; ConnHandle); 

BEGIN 

{ If not listen or open pending, return error condition. } 

{ Terminate listen or open process. } 

{ Close the physical layer driver. } 

END; 

cmAcceptMsg 

The Connection Manager will pass cmAcceptMsg to your tool when the application has called 
the cmAccept routine. When passed to your tool, pi will contain 1 if your tool should accept 
the open request, or 0 if it should reject it. 

Once your tool receives this message, it should clear the cmstatusincomingCaiiPresent 
bit the next time it receives a cmstatusMsg. 

The sample code shows a template into which you can code your tool’s response to 
cmAcceptMsg. When finished, your tool should return an appropriate error code. 

FUNCTION myAccept(hConn : ConnHandle; accept : INTEGER) : CMErr; 

BEGIN 

{ If the connection is already open, return error condition. } 

if accept <> cmAcceptOK then 

begin 

{ Terminate the logical connection listen process. } 

{ Close the physcial layer driver. } 

end 

else 

{ set the open status bit } 

END; 

cmActivateMsg and cmDeactivateMsg 

The Connection Manager will pass cmActivateMsg or cmDeactivateMsg tO yOUr tOOl 
when the application requires your tool to perform an action, such as installing or removing a menu 
from the menu bar in response to an activate or deactivate message. 

cmSuspendMsg and cmResumeMsg 

The Connection Manager will pass cmSuspendMsg or cmResumeMsg to your tool when the 
application requires your tool to perform an action, such as installing or removing a menu from the 
menu bar in response to a suspend or resume message. 
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cmlnitMsg 

The Connection Manager will pass cminitMsg to your tool after the following sequence of 
events occurs. When a tool or application calls CMNew, the Connection Manager allocates space for 
the connection record. It then fills in some of the fields, based upon information that was passed in 
the parameters to the call. The Connection Manager fills in the conf ig and oidconfig fields 
by calling CMOefauit. Then, the Connection Manager passes cminitMsg to your tool. After 
your tool has finished responding to cminitMsg, the Connection Manager calls CMVaiidate. 

If your tool allocates space for internal buffers in the buffer Array field of the connection 
record, applications and the Connection Manager must not manipulate the space. Also, your tool is 
responsible for freeing the space (in response to cmoisposeMsg). Connection tools are not 
required to use the bufferArray field. 

The sample code shows how your tool can respond to cminitMsg. After executing the code 
necessary to respond to cminitMsg, your code should pass back an appropriate osErr or 

CMErr. 

FUNCTION myinit(hConn: ConnHandle): CMErr; 

VAR 

state: SignedByte; 

BEGIN 

myinit := noErr; { 

state := HGetState(Handle(hConn)); { 

HLock(Handle(hConn)); { 

WITH hConn'"'^ DO 
BEGIN 

flags := BOR(flags, cmData) ; { yes we do data } 

IF BAND (flags, cmAttn) <> 0 THEN { turn off attention } 

flags := BXOR(flags, cmAttn); 

IF BAND (flags, cmCntl) <> 0 THEN { turn off control } 

flags := BXOR(flags, cmCntl); 

errCode := noErr; { optimism reigns } 

{ need to check MemErr here } 

bufferArray[cmDataIn] := NewPtr(bufSizes[cmDataIn]); 
bufferArray[cmDataOut] := NewPtr(bufSizes[cmDataOut]); 

private := PrivatePtr(NewPtr(SIZEOF(PrivateData) ) ) ; 

WITH private'" DO 
BEGIN 

{ fill in private data structure here } 

END; 

END; 

HSetState(Handle(hConn), state); 

END; 


optimism } 

save handle state } 

lock it down } 
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cmDisposeMsg 

A tool or application will call CMDispose when it must dispose of a connection record and its 
associated data structures. 

The Connection Manager passes cmDisposeMsg to your tool before disposing of the conf ig 
and oidconf ig fields of the connection record. Next, the Connection Manager disposes of the 
connection record. 

To handle cmDisposeMsg, your tool should dispose of any buffers allocated in response to 
cminitMsg and any private data storage (referenced off of cmPrivate in the connection 
record). Your tool must not attempt to dispose of either config or oidconf ig in the connection 
record, or of the connection record itself. Doing so will cause a system crash. 

The sample code shows how your tool can respond to cmDisposeMsg. 

FUNCTION myDispose(hConn: ConnHandle): CMErr; 

VAR 

pPrivate: PrivatePtr; { tool privates } 


BEGIN 

myDispose := noErr; 

{ if the connection is open then call CMClose on it } 

DisposPtr( Ptr (hConn'"'" .private) ); 

DisposPtr( Ptr (hConn'^'" .buf ferArray [cmDataIn] ) ); 

DisposPtr( Ptr(hConn^^.bufferArray[cmDataOut]) ); 

END; 

cmReadMsg and cmWriteMsg 

A tool or application will call CMRead when it requires your tool to read data from a remote 
entity. Likewise, a tool or application will call CMWrite when it requires your tool to write data to 
a remote entity. The Connection Manager will handle these calls by passing cmReadMsg or 
cmWriteMsg to the appropriate connection tool. 

If a channel is requested that is not supported by your tool (for example, if a read is requested 
on the attention channel when the attention channel is not supported), your tool should return 

cmNotSupperted. 

After executing the code necessary to respond to cmReadMsg or cmwriteMsg, your tool 
should pass back an appropriate osErr or cMErr. 

When cmReadMsg Or cmwriteMsg iS passed tO yOUr tool, pi points to the CMDataBuf fer 
record, p2 points to the cMcompietorRecord record, and p3 contains the timeout value. The 
timeout value specifies a time period, in ticks, within which the read operation must complete. If 
your tool does not complete within the specified time, it should pass back a timeout error. An 
application passes -1 when it wants no timeout. If the application specifies 0, your connection tool 
should read as many bytes, up to toRead bytes, as it can in one read attempt. 

Depending on the connection protocol your tool is supporting, your tool might ignore the 
timeout parameter. 
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The CMDataBuffer record 


A DataBuffer record contains information about where the read or write buffer is located, how 
many bytes are supposed to be read or written, the channel that is to be used, and an end-of- 
message flag. Your tool should be able to accommodate the data structure defined here: 

TYPE 

CMDataBufferPtr = 

CMDataBuffer = 

thePtr : 

count : 

channel : 

flags : 

END; 

These are the valid values for channel: 

CONST 

cmData = $00000001; 

cmCntl = $00000002; 

cmAttn = $00000004; 


^CMDataBuffer; 

RECORD 

Ptr; 

LONGINT; 
CMChannel; 
CMFlags; 


The CompletorRecord record 


Your tool uses a CMCompietorRecord Structure when it receives a message to process 
asynchronously. This record contains a pointer to a completion routine your tool calls upon 
completion of the specified operation. 

If the operation is to be performed asynchronously, the async field of the 
CMCompietorRecord is TRUE and the pointer to the completion routine is in the 
completionRoutine field. 

If the operation is to be performed synchronously, the async field of the 
CMCompietorRecord is FALSE. Your tOOl should ignore the completionRoutine field 
in this case. 

The CMCompietorRecord is Created in a local stack frame by the Connection Manager; 
therefore, your tool should copy the contents of the CMCompietorRecord data structure if 
any information in it will be needed later. 


TYPE 

CMCompletorPtr 

CMCompietorRecord 

async 

completionRoutine 

END; 


CMCompietorRecord; 

RECORD 

BOOLEAN; 

ProcPtr; 


cmReadMsg 

If your tool receives cmReadMsg with timeout 0, it should return immediately, even if it 
cannot read all the requested bytes. For example, if your tool receives a read request with timeout 
0 for 512 bytes, and only 63 are available, your tool should read 63 bytes, put 63 in the count field of 
the CMDataBuffer, and return noErr. 
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FUNCTION myRead(hConn : ConnHandle; dp : CMDataBufferPtr; 

completor : CMCompletorPtr;timeout : LONGINT) : CMErr; 

VAR 

pPrivate : privateptr; 

err : OSErr; 


BEGIN 


dp'", flags := 0; { set flags to zero, this tool does not support it } 

pPrivate := privateptr (hConn'"'".cmPrivate) ; 

{ is connection open ? } 

if (BAND (pPrivate'". status , cmStatusOpen) = 0) then 
begin 

myRead := cmNotOpen; 

EXIT(myRead) ; 

end; 

if ( dp^.channel <> cmData) then { trying to do something we cannot support } 
begin 

dp^.count := 0; 

myRead := cmNotSupported; 

EXIT(myRead) ; 

end; 

{ if async read then install VBL task to check time out 
else check the available data to read in driver buffer } 

{ do the read } 

err := PBRead( ParmBlkPtr (QpPrivate'" .myRBlk. theParamBlk) , 
completor^.async ); 

{ handle err condition } 
if err <> noErr then 
begin 

dp^.count := 0; 
hConn'"'".errCode := err; 
myRead := err; 

EXIT(myRead); 

end; 

{ set the bytes read } 

if (pPrivate'" .myRBlk. theParamBlk. ioActCount = 0) & 

((completor <> nil) & completor^.async) then 

begin 

dp'", count := 0; 

hConn'"'". asyncCount [cmDataIn] 0; 

end 

else 
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begin 


end; 


dp'". count : = pPrivate'". myRBlk. theParamBlk. ioActCount ; 
hConn'"^ .asyncCount [cmDataIn] : = 

pPrivate'" .myRBlk. theParamBlk. ioActCount; 


myRead noErr; 

END; 


cmWriteMsg 

If your tool receives a cmwriteMsg with timeout 0, it should return immediately, even if it 
cannot write all the requested bytes. For example, if your tool receives a write request with 
timeout 0 for 512 bytes, and only 63 can be written immediately, your tool should write 63 bytes, 
put 63 in the count field of the CMDataBuf fer, and return noErr. 

FUNCTION myWrite(hConn ; ConnHandle; dp : CMDataBufferPtr; 

completor : CMCompletorPtr;timeout : LONGINT) : CMErr; 

VAR 

pPrivate ; privateptr; 

err : OSErr; 

BEGIN 

pPrivate := privateptr (hConn'"'". cmPrivate) ; 

{ is connection open ? } 

if (BAND (pPrivate'". status , cmStatusOpen) = 0) then 
begin 

myWrite := cmNotOpen; 

EXIT(myWrite); 

end; 

if ( dp'".channel <> cmData) then 

{ trying to do something we cannot support } 

begin 

dp'", count := 0; 

myWrite := cmNotSupported; 

EXIT(myWrite); 

end; 

{ install VBL task to check time out if async write } 

err PBWrite ( ParmBlkPtr (@pPrivate'" .myWBlk.theParamBlk), completor'".async ); 
{ handle error condition } 

if err <> noErr then 
begin 

dp^.count := 0; 
hConn'"'" .errCode ;= err; 
myWrite := err; 

EXIT(myWrite); 

end; 
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{ set the bytes write } 

{ ** Be sure to have the ShortCircuit compiler variable turned on ** } 

if (pPrivate'" .myWBlk. theParamBlk. ioActCount = 0) 

AND ( (completor <> nil) AND completor'^. async) then 

begin 

dp'^. count := 0; 

hConn'^^ . asyncCount [cmDataOut] := 0; 

end 

else 

begin 

dp'", count := pPrivate^ .myWBlk. theParamBlk. ioActCount; 

hConn'"'" .asyncCount [cmDataOut] ;= pPrivate'".myWBlk. theParamBlk. ioActCount 

end; 

myWrite := noErr; 

END; 

cmStatusMsg 

The Connection Manager will send cmstatusMsg to your tool when an application requires your 
tool to send it information about a connection. 

The sample code shows how your tool can respond to cmstatusMsg. After executing the 
code necessary to respond to cmstatusMsg, your code should pass back both an appropriate 
osErr or CMErr. Also, pi should Contain a pointer to CMBuffersizes, and p2 should 
contain a pointer to a variable that returns the connection status flags. 

Connection status flags are a bit field, with each bit corresponding to a particular status 
attribute. You can find a description of the status attributes in “cMStatus: Getting Connection 
Status Information” in Chapter 3. 

FUNCTION myStatus(hConn : ConnHandle; Var size : CMBufferSizes; 

Var theflag : LONGINT) : CMErr; 

VAR 

pPrivate ; privateptr; 

count : LONGINT; 

err ; OSErr; 

BEGIN 

pPrivate := privateptr (hConn'"'". cmPrivate) ; 

theflag := 0; 

if (BAND (pPrivate'". status, cmStatusOpen) = 0) then { is connection open ? } 

size[cmDataIn] := 0 

else 

begin 

err ;= SerGetBuf ( pPrivate'". outrefnum, count ); 

{ Check output driver buffer } 
size[cmDataOut] := count; 

err := SerGetBuf ( pPrivate'". inrefnum, count ); 

{ Check input driver buffer } 
size[cmDataIn] := count; 
if (count > 0) then 

theflag := BOR(theflag, cmStatusDataAvail); 
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end; 


{ Set data availabe bit } 
theflag BOR(theflag, cmStatusOpen); 
{ the connection is established } 


END; 


{ set the other flags } 
if BAND (pPrivate'". status, 
then theflag 

if BAND (pPrivate'^. status, 
then theflag 
if BAND (pPrivate'". status, 
then theflag 
if BAND (pPrivate'". status, 
then theflag 
myStatus := noErr; 


cmStatusDRPend) = cmStatusDRPend 
:= BOR(theflag, cmStatusDRPend); 
cmStatusDWPend) = cmStatusDWPend 
: = BOR(theflag, cmStatusDWPend); 
cmStatusBreakPending) = cmStatusBreakPending 
:= BOR(theflag, cmStatusBreakPending); 
cmStatusListenPend) = cmStatusListenPend 
:= BOR(theflag, cmStatusListenPend); 


cmOpenMsg 

Your tool’s main code resource will receive cmopenMsg from the Connection Manager when an 
application or tool requires your tool to open a connection. When passed to your tool, pi contains 
a pointer to CMCompietorRecord, and p2 contains the timeout value in ticks. 

The sample code shows a template into which you can code your tool’s response to 
cmOpenMsg. The Connection Manager, after the connection tool passes control back to it, disposes 
of CMCompietorRecord. Therefore, your tool should copy CMCompletorRecord if it will 
need any information the record contains. 

After executing the code necessary to respond to cmopenMsg, your code should pass back an 
appropriate osErr or cMErr. 


FUNCTION myOpen(hConn : ConnHandle; 

timeout : LONGINT) 


VAR 

pPrivate 
config 
errl,err2 
theSerial 
savedState 


: privateptr; 

: configptr; 

: OSErr; 

: CRMSerialPtr; 
: SignedByte; 


completor : CMCompletorPtr; 
: CMErr; 


BEGIN 


pPrivate := privateptr (hConn'"'^. cmPrivate) ; 
config := conf igptr (hConn'^^ . conf ig) ; 


{ get the CRM device info } 

theSerial := GetSerialPtr (config'^ .portName) ; 


{ check if drivers are already open 

if drivers are open, warn the application } 

{ first open output driver, then input driver } 
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myOpen := noErr; 

savedState := HGetState (Handle (theSerial'". outputDriverName) ) ; 

HLock (Handle (theSerial'". outputDriverName) ) ; 

errl := OpenDriver (theSerial^ .outputDriverName'^'", pPrivate'". outrefnum) ; 
HSetState (Handle (theSerial'". outputDriverName) , savedState) ; 
if (errl = 0) then { output opened successfully } 

begin 

savedState := HGetState (Handle (theSerial'^ . inputDriverName) ) ; 

HLock (Handle (theSerial'". inputDriverName) ) ; 
err2 := OpenDriver (theSerial'". inputDriverName'"'", 
pPrivate'". inrefnum) ; 

HSetState (Handle (theSerial'". inputDriverName) , savedState) ; 
if (err2 = 0) then { input opened successfully } 

pPrivate'". status := cmStatusOpen 
else { input failed } 

begin 

myOpen := err2; 

err2 := CloseDriver (pPrivate'".outrefnum) ; { so close output } 

end; 

end 

else myOpen errl; 

{ call completor routine here if is async open } 


END; 


cmCloseMsg 

Your tool’s main code resource will receive cmcioseMsg from the Connection Manager when an 
application or tool requires your tool to close a connection. 

The sample code shows how your tool can respond to cmcioseMsg. When passed to your 
tool, pi contains a pointer to CMCompietorRecord, and p2 contains the timeout value in 
ticks. The Connection Manager, after the connection tool passes control back to it, disposes of 
CMCompietorRecord. Therefore, your tool should copy CMCompietorRecord if it will need 
any information the record contains. 

After executing the code necessary to respond to a cmcioseMsg , your code should pass back 
an appropriate osErr or cMErr. 

FUNCTION myClose(hConn : ConnHandle; completor : CMCompletorPtr; 
now : LONGINT) : CMErr; 

VAR 

pPrivate : privateptr; 

err : OSErr; 


BEGIN 


pPrivate := privateptr (hConn'"^ . cmPrivate) ; 

{ is connection open ? } 

if (BAND (pPrivate'". status , cmStatusOpen) = 0) then 


246 Macintosh Communications Toolbox Reference 





begin 


myClose := cmNotOpen; 
EXIT(myClose); 


end; 


{ if break pending, kill break VBL } 

{ if now, kill pending reads and writes 

else wait for pending reads and writes to clear } 

{ close input and output drivers } 
err := CloseDriver (pPrivate'". inrefnum) ; 
if err <> noErr then myClose := err; 
err ; = CloseDriver (pPrivate'". outrefnum) ; 
if err <> noErr then myClose := err; 

{ call completor routine here if is async close } 


END; 


cmBreakMsg 

Your tool’s main code resource will receive cmBreakMsg when an appliation or tool requires 
your tool to effect a break operation upon a connection. 

When passed to your tool, pi contains duration in ticks, and p2 contains a pointer to 
CMCompletorRecord. 

The sample code shows how your tool can respond to cmBreakMsg. The Connection 
Manager, after the connection tool passes control back to it, disposes of CMCompietorRecord. 
Therefore, your tool should copy CMCompietorRecord if it will need any information the 
record contains. 

FUNCTION myBreak(hConn: ConnHandle; duration: LONGINT; 


completor: CMCompletorPtr): CMErr; 


VAR 


pPrivate 
pConfig 
err 
too 


PrivatePtr; 
ConfigPtr; 
OSErr; 
LONGINT; 


BEGIN 


myBreak 


noErr; 


{optimism} 


pPrivate 
pConfig 


PrivatePtr (hConn^'" .private) ; 
Conf igPtr (hConn'"'^. conf ig) ; 


if ( BAND (pPrivate'^. status, cmStatusOpen) = 0 ) THEN 


{ not open } 


BEGIN 

myBreak := cmNotOpen; 
Exit(myBreak); 


END; 
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{ break pending } 


IF (pPrivate'" .breakPending) THEN 
BEGIN 

myBreak := cmNoErr; 

Exit(myBreak); 

END; 

IF completor'". async THEN 
BEGIN 

{ do it asynchronously } 

{ start the break } 

{ start a timer (VBL or such) when it completes it will 

turn off the break and then call the completion routine 
if necessary } 

END 

ELSE 

BEGIN 

{ start the break } 

Delay(duration, foo) ; 

{ end the break } 

END; 

END; 


cmlOKillMsg 

Your tool’s main code resource will receive cmioKiiiMsg when a tool or application requires 
your tool to terminate a pending asynchronous input or output request. When passed to your tool, 
pi contains the channel that cmiOKiiiMsg should affect. 

The sample code shows how your tool can respond to cmiOKiiiMsg. 

FUNCTION mylOKill(hConn ; ConnHandle; channel : INTEGER) : CMErr; 

VAR 

pPrivate : privateptr; 

localBlk ; HParamBlockRec; 

Err ; OSErr; 


BEGIN 


pPrivate := privateptr (hConn'"'". cmPrivate) ; 

if (channel <> INTEGER(cmDataIn)) AND (channel <> INTEGER(cmDataOut)) then 
begin 

mylOKill := cmNotSupported; 

{ can't cancel something I don't supPrivateort } 

EXIT(mylOKill); 

end; 

localBlk.ioCompletion ;= nil; 

if (channel = INTEGER(cmDataIn)) then { cancel read } 

localBlk.ioRefNum := pPrivate^.myRBlk.theParamBlk.ioRefNum 
else { cancel write } 

localBlk.ioRefNum := pPrivate^.myWBlk.theParamBlk.ioRefNum; 
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Err : = 


PBKilllO(ParmBlkPtr(@localBlk) , false) ; 


if (Err <> noErr) then hConn'^'". errCode := Err; 
mylOKill := Err; 

END; 


cmEnvironsMsg 

The Connection Manager will send cmEnvironsMsg to your tool when an application requires 
your tool to send it information about the connection environment. The connEnvironRec, 
which contains this information, is shown here. 


TYPE 


ConnEnvironRecPtr 
ConnEnvironRec = 

version 

baudRate = 

dataBits = 

channels - 

swFlowControl 
hwFlowControl = 


'"ConnEnvironRec; 
PACKED RECORD; 
INTEGER; 

LONGINT; 

INTEGER; 
CMChannel; 
BOOLEAN; 

BOOLEAN; 


TYPE 


CONST 


CONST 


TYPE 


flags 

END; 


= CMFlags; 

CMFlags 

= 

INTEGER; 

cmFlagsEOM 


$0001; 

cmData 


= $00000001; 

cmCntl 


- $00000002; 

cmAttn 


= $00000004; 

cmDataClean 

sr 

$00000100; 

cmCntlClean 

= 

$00000200; 

cmAttnClean 

= 

$00000400; 

cmNoMenus 


$00010000; 

cmQuiet 

= 

$00020000; 

CMChannel 

. 

INTEGER; 


This sample code shows how your tool can respond to cmEnvironsMsg. 

FUNCTION myEnvirons(hConn: ConnHandle; VAR theEnvirons: ConnEnvironRec): 
CMErr; 

VAR 

pConfig: ConfigPtr; 
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BEGIN 


pConfig := ConfigPtr (hConn'^'".config) ; { get the config handle} 

myEnvirons := noErr; { optimism } 


IF theEnvirons.version < curConnEnvRecVers THEN 

myEnvirons := envBadVers { bad environment version } 

ELSE 

BEGIN 

IF theEnvirons.version > 1 THEN { too advanaced for me } 

myEnvirons := envVersTooBig; { but give it a whirl } 


WITH theEnvironsDO 
BEGIN 

dataBits := pConfig'^.dataBits; 
baudrate := pConfig'" .baudrate; 
swFlowControl := ((pConfig^.shaker.fInX) AND 

(pConf ig'". shaker. fXOn) ) ; 

hwFlowControl := ((pConfig^.shaker.fDTR) OR 

(pConfig'". shaker. fCTS) ) ; 

flags ;= 0; {no special flags supported } 

channels := cmData; { data channel only } 

END; 

END; 

END; 


Completion routines 

when your connection tool calls Mycompietion, the errcode field of the connection record 
contains the appropriate error code. Because the errCode field of the connection record is used 
by all of the Connection Manager routines, the connection tool must first save the current value of 
the errCode field, and then set it to the appropriate code for the completion, call the completion 
routine, then restore the previously saved value. If your tool has multiple outstanding 
asynchronous operations, your tool should disable interrupts while the completion routine is 
executing. 

When your tool calls the completion routine in response to the completion of an asynchronous 
read or write, the asynccount field of the connection record contains the actual number of bytes 
read or written. 
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Quick reference 

This section contains reference information for the data structures, resource names, and resource 
types that you need to write a connection tool. A table at the end of this section lists all the 
messages the Connection Manager sends to your tool, and what is passed in the parameters with 
each message. 


Data structures 

CMDataBuffer 

TYPE 

CMDataBufferPtr 

CMDataBuffer = 

thePtr : 

count : 

channel : 

flags : 

END; 

CMCompletorRecord 

TYPE 

CMCompletorPtr 

CMCompletorRecord 

async 

completionRoutine 

END; 

SetupStruct 

CMSetupPtr 

CMSetupStruct 

theDialog : 

count : 

theConfig : 

procID ; 

END; 


'^CMDataBuffer; 

RECORD 

Ptr; 

LONGINT; 
CMChannel; 
CMFlags; 


'"CMCompletorRecord; 

RECORD 

BOOLEAN; 

ProcPtr; 


'"CMSetupStruct; 
RECORD 
DialogPtr; 
INTEGER; 

Ptr; 

INTEGER 
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Resource names 


FUNCTION 

cdef(hConn: ConnHandle; 
LONGINT) : LONGINT; 

msg: 

INTEGER; 

Pl/ 

P2, 

P3: 

FUNCTION 

cval(hConn: ConnHandle; 

LONGINT) ; LONGINT; 

msg: 

INTEGER; 

Pl/ 

P2, 

p3: 

FUNCTION 

cset(pSetup: CMSetupPtr; 
LONGINT) : LONGINT; 

msg; 

INTEGER; 

pl 

, P2 

/ P3 

FUNCTION 

cscr(hConn: ConnHandle; 
LONGINT) : LONGINT; 

msg: 

INTEGER; 

pl/ 

P2, 

P3: 

FUNCTION 

cloc(hConn: ConnHandle; 
LONGINT) ; LONGINT; 

msg: 

INTEGER; 

pl/ 

P2, 

P3: 


Resource types 


type 


>; 


'cbnd' { 

integer = $$CountOf(TypeArray) - 1; 
array TypeArray { 

literal longint; /* Type */ 

integer = $$CountOf(IDArray) - 1; 
wide array IDArray { 

integer; /* Local ID */ 

integer; /* Actual ID */ 

}; 

}/ 
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Table 9-1 Connection Manager messages and parameters 
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Indicates the routine is a function that returns a longint. 






THIS CHAPTER tells you how to write the main code resource for a 
terminal tool. You will need to include six code resources in your tool; they are 
described in Chapter 8. You should read that chapter, as well as Chapter 4, 
before reading this chapter. 

This chapter describes all the messages, parameters, and data structures that 
the Terminal Manager passes to your tool’s main code resource. Also in this 
chapter is sample code (with pseudocode mixed in) that will help you 
understand what your tool should do when it receives any of the messages. A 
quick reference at the end of the chapter shows you what you should name 
your six terminal tool resources. It also lists the messages the Terminal 
Manager sends to your tool, and the parameters that the Terminal Manager 
passes with each message. 
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Your terminal tool’s main code resource 


The purpose of the main code resource is to parse messages from the Terminal Manager and then to 
branch to a routine that can handle each message. The main code resource should be a resource of 
type ' tde f ', and should be able to accept the parameters shown here. 

FUNCTION tdef(hTerm: TermHandle; msg: INTEGER; pi, p2, p3: 

LONGINT) : LONGINT; 

The accepted messages are as follows: 

CONST 


tminitMsg 

= 

0 


tmDisposeMsg 

= 

1 


tmSuspendMsg 

= 

2 


tmResumeMsg 


3 


tmMenuMsg 

= 

4 


tmEventMsg 

= 

5 


tmActivateMsg 

= 

6 


tmDeactivateMsg 

= 

7 


tmIdleMsg 

= 

50; 

tmResetMsg 

= 

51; 

tmKeyMsg 

= 

100 

tmStreamMsg 

= 

101 

tmResizeMsg 

= 

102 

tmUpdateMsg 

= 

103 

tmClickMsg 

= 

104 

tmGetSelectionMsg 

= 

105 

tmSetSelectionMsg 

= 

106 

tmScrollMsg 

= 

107 

tmClearMsg 

= 

108 

tmGetLineMsg 

ss 

109 

tmPaintMsg 

= 

110 

tmCursorMsg 

= 

111 

tmGetEnvironsMsg 

= 

112 

tmDoTermKeyMsg 

= 

.113 

tmCountTermKeysMsg 

= 

114 

tmGetIndTermKeyMsg 

= 

115 


Your tool can return an appropriate operating-system error code, or tmNot supported if it does 
not understand the message it received. 

tmlnitMsg 

The Terminal Manager will pass tminitMsg to your tool after the following sequence of events 
occurs. When a tool or application calls TMNew, the Terminal Manager allocates space for the 
terminal record. It then fills in some of the fields, based upon information that was passed in the 
parameters to the call. The Terminal Manager fills in the config and oidconf ig fields by 
calling TMDefauit. Then the Terminal Manager passes tminitMsg to your tool. After your 
tool has finished responding to tminitMsg, the Terminal Manager calls TMvaiidate. 
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BEGIN 


theChar := CHAR( BAND( myEvent.message, charCodeMask) ); 
theKeyCode := CHAR( BAND( myEvent.message, keyCodeMask) ); 
theModifier := myEvent.modifiers ; 

theState := HGetState( Handle( hTerm) ) ; 

HLock( Handle( hTerm) ) ; 

With hTerm'^'^ Do 
Begin 

{ do special keyboard mapping if the keycode isn't -1 } 

{ if keycode is -1, that is, fake keyDown event } 

{ transmit data if the terminal is online } 

{ echo data to the screen if online is off or localecho is true } 

END; 

HSetState ( Handle(hTerm) , theState); 

END; 


tmStreamMsg 

The Terminal Manager will pass tmstreamMsg to your tool when the application has requested 
the TMstream routine. When passed to your tool, pi will point to the buffer of incoming data; 
p2 will contain the length of the buffer in bytes; and p3 will contain flags, which the 
application passed to TMStream. The sample code shows a template into which you can code 
your tool’s response to tmstreamMsg . 

After executing the code necessary to respond to a tmstreamMsg, your tool should return 
the number of characters it processed. 


FUNCTION 

VAR 


TermToolStream(hTerm: TermHandle; theBuffer: Ptr; 

theBufferSizeiLONGINT ; flag: CMFlags):LONGINT; 


theState 

thePtr 

i 

privatePtr 


SignedByte; 

Ptr; 

INTEGER; 

TERMINALPrivatePtr ; 


BEGIN 

theState := HGetState ( Handle( hTerm) ) ; 

HLock( Handle( hTerm) ) ; 

With hTerm^'" Do 
Begin 

{ do special handling if flag is equal to EOM } 

privatePtr := TERMINALPrivatePtr( tmPrivate); 

With privatePtr'" Do 
BEGIN 

thePtr ;= tmprivatetermbuffer; 

thePtr := Ptr ( Ord(thePtr) + 

tmprivatecurrentrow * tmprivatecurrentcol) 
FOR i := 1 TO theBufferSize DO 
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BEGIN 


{ process data in theBuffer, such as moving the 
cursor position, etc. } 

{ if data in theBuffer isn't a special escape sequence } 
{ assign data into our private terminal tool buffer } 

thePtr := Ptr ( LONGINT ( theBuffer ) + i); 

{ advance tmprivatecurrentcol } 

tmprivatecurrentcol := tmprivatecurrentcol + 1; 

END; 

{ return the number of chars we have processed } 

TermToolStream := LONGINT( theBufferSize); 

END; 

END; 

HSetState ( Handle(hTerm) , theState); 

END; 

tmActivateMsg and tmResumeMsg 

Your tool will receive tmActivateMsg when the application requires your tool to process an 
activate event (such as inserting menus into the menu bar, modifying a selection, or making the 
cursor blink) for a window that belongs to the Terminal Manager. The sample code shows a 
template into which you can code your tool’s response to tmActivateMsg. 

Your tool receives tmResumeMsg from the Terminal Manager when the application returns 
to the foreground in MultiFinder. Your tool can call the same routine in response to receiving 
tmResumeMsg aS it Calls in response to receiving tmActivateMsg. 

PROCEDURE TermToolActivate( hTerm:TermHandle); 

VAR 

privatePtr : TERMINALPrivatePtr; 

theState : SignedByte; 

BEGIN 

theState := HGetState( Handle( hTerm)); 

HLock ( Handle( hTerm) ); 

With hTerm'"'" Do 
Begin 

privatePtr := TERMINALPrivatePtr ( tmPrivate); 

{ turn on the selection if there's any } 

IF NOT EmptyRect( selection.selRect ) THEN 
HiliteSelection ( hTerm); 

{ put up my tool's menu if tmNoMenus isn't true } 

IF ( BAND( flags, tmNoMenus ) = 0 ) THEN 
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PROCEDURE TermToolUpdate( hTerm:TermHandle ; visRgn:RgnHandle); 

VAR 

theState : SignedByte; 

BEGIN 

theState := HGetState ( Handle( hTerm) ) ; 

HLock( Handle ( hTerm) ) ; 

With hTerm^'^ Do 
Begin 

{ redraw the terminal area. The area to be drawn is specified by } 
{ the region handle passed in. } 

End; 

HSetState( Handle(hTerm), theState); 

END; 



tmClickMsg 

Your tool will receive tmciickMsg from the Terminal Manager when the application requires 
your tool to handle a mouse-down event in the terminal emulation window; it should respond by 
calling the application’s click-loop procedure. Your tool should support placing and dragging the 
cursor. When passed to your tool, pi will contain a pointer to the event record. 

The sample code shows a template into which you can code your tool’s response to 

tmClickMsg. 


PROCEDURE TermToolClick( hTerm:TermHandle ; myEvent:Eventrecord); 
VAR 


theState : SignedByte; 

clickInCachArea : Boolean; 

BEGIN 

theState HGetState ( Handle( hTerm) ) ; 

HLock( Handle( hTerm) ) ; 

clickInCachArea := FALSE ; 

With hTerm'^'^ Do 
Begin 

{ call the clickloop if there’s any } 

if clikLoop <> NIL THEN 

BEGIN 

clickInCachArea := CallclikLoop( refCon, 

END; 

if NOT clickInCachArea THEN 
BEGIN 



clikLoop ) ; 


{ mouse click is in the terminal area, track mouse } 

END; 

End; 

HSetState( Handle(hTerm), theState); 

END; 
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tmMenuMsg 

Your tool will receive tmMenuMsg from the Terminal Manager when the user has chosen an item 
from a menu that belongs to your terminal tool. When passed to your tool, pi will contain the 
menu ID, and p2 will contain the menu item. The sample code shows a template into which you 
can code your tool’s response to tmMenuMsg. 

After your tool has handled tmMenuMsg, it should return 0 if it did not handle the menu 
event, and 1 if it did. 

FUNCTION TermToolMenu( hTerm:TermHandle ; menuID, menultem:INTEGER ) iLONGINT; 

VAR 

theState : SignedByte; 

privatePtr : TERMINALPrivatePtr; 

BEGIN 

theState := HGetState ( Handle( hTerm) ) ; 

HLock( Handle( hTerm) ) ; 

With hTerm'^^ Do 
BEGIN 

privatePtr := TERMINALPrivatePtr( tmPrivate ); 

With privatePtr^ Do 
BEGIN 

{ does the menuID belong to the terminal? } 

IF menuID = tmprivateMenuID THEN 
BEGIN 

{ yes, it's one of ours, handle it based on the menultem } 

{ unhilite the menu title } 

HiliteMenu( tmprivateMenuID ); 

{ if the menu belongs to the terminal tool, return 1 } 
TermToolMenu := 1 ; 

END 

ELSE 

{ if the menu doesn't belong to the terminal tool, return 0 } 
TermToolMenu := 0 ; 

END; 

END; 

HSetState ( Handle(hTerm) , theState); 

END; 

tmGetSelectionMsg 

Your tool needs to be able to handle tmGetseiectionMsg to support cut and copy operations 
in the terminal emulation window. The sample code shows a template into which you can code 
your tool’s response to tmGetseiectionMsg. 

After responding to tmGetseiectionMsg, your tool should resize the data block (the 
passed-in handle) by calling setHandiesize (pi, newsize), and a pointer to the scrap type 
(ResType) in p3. Your tool should also return an error code, if appropriate; zero if there was no 
selection; or the size of the selected data. 
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FUNCTION TermToolGetSelection( hTerm:TermHandle ; DataHandle:Handle; 

VAR selResType:ResType)rLONGINT; 

VAR 

theState : SignedByte; 

datasize : LONGINT; 

BEGIN 

theState := HGetState ( Handle( hTerm) ) ; 

HLock( Handle ( hTerm) ) ; 

With hTerm'^'^ Do 
BEGIN 

IF NOT EmptyRect( selection.selRect ) THEN 
BEGIN 

{ there's a selection } 

{ calculate the size of the selection } 
datasize := GetSelectionSize( hTerm); 

{ grow DataHandle according to the size } 
SetHandleSize(DataHandle, datasize ); 

{ copy the data into DataHandle } 

selResType := 'TEXT'; 

TermToolGetSelection := datasize ; 

END 

ELSE 

{ there's no selection } 

TermToolGetSelection := 0 ; 

END; 

HSetState ( Handle(hTerm) , theState); 

END; 


tmSetSelectionMsg 

An application will call TMSetseiection when it requires your tool to highlight an area of the 
terminal emulation window. When passsed to your tool, pi will point to the field that needs to 
be highlighted, and p2 will describe the type of selection. The example code shows a template 
into which you can code your tool’s response to tmsetseiectionMsg. 

PROCEDURE TermToolSetSelection( hTerm:TermHandle ; mySelection:TMSelection; 

myselType:LONGINT); 

VAR 

theState : SignedByte; 

BEGIN 

theState := HGetState ( Handle( hTerm) ) ; 

HLock( Handle( hTerm) ) ; 

With hTerm'"'" Do 
BEGIN 

IF NOT EmptyRect( selection.selRect ) THEN 

{ dehilite old selection if there's any } 
DeHiliteSelection ( hTerm); 

{ assign new selection record to the terminal record } 
selection := mySelection ; 
selType := myselType; 
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HiliteSelection( hTerm ) ; 


END; 


END; 

HSetState ( Handle(hTerm) , theState); 


tmScrollMsg 

An application will call tmscroii when it requires your tool to scroll the terminal emulation 
region either horizontally or vertically. (The application is responsible for scrolling the cache area, if it 
supports one.) When passed to your tool, pi will contain the amount of horizontal scrolling, and 
p 2 will contain the amount of vertical scrolling. The example code shows a template into which 
you can code your tool’s response to tmscroiiMsg. 


PROCEDURE TermToolScroll ( hTerm:TermHandle; deltaH, deltaV:LONGINT ); 
VAR 

theState : SignedByte; 

updatergn : RgnHandle; 

BEGIN 

theState := HGetState ( Handle( hTerm) ) ; 

HLock ( Handle( hTerm) ) ; 

With hTerm^'^ Do 
BEGIN 



END; 


updatergn := NewRgn; 

ScrollRect( viewRect, deltaH, deltaV, updatergn ); 
{ update the newly scrolled in area } 

DisposeRgn( updatergn); 

END; 

HSetState ( Handle(hTerm) , theState); 


tmResetMsg 

Your tool will receive tmResetMsg when the application requires your tool to reset the terminal 
emulation window. This reset operation should purge all local screen buffers, be a local operation, 
and call the cache procedure if tmSaveBef oreciear is set in the terminal record. 

The code sample shows a template into which you can code your tool’s response to 

tmResetMsg. 


PROCEDURE TermToolReset( hTerm:TermHandle ); 

VAR 

theState : SignedByte; 

error : Boolean; 

BE(?IN 

theState := HGetState ( Handle( hTerm) ) ; 

HLock( Handle( hTerm) ) ; 

With hTerm'^'^ Do 
BEGIN 


{ clear the screen } 
TermToolClear( hTerm ) ; 

{ copy the saved configuratioi 
BlockMove( oldConfig, config, 

{ call the validate routine t< 


into the current configuration record 
sizeof( ToolConfigRecord) ); 
update my tool's private record } 


} 
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error := TMValidate( hTerm); 

END; 

HSetState ( Handle(hTerm), theState); 

END; 

tmClearMsg 

Your tool will receive tmciearMsg when the application needs your tool to clear the terminal 
emulation window. This clear operation should purge all local saeen buffers, be a local operation, 
and call the cache procedure if tmSaveBeforeciear is set in the terminal record. 

The code sample shows a template into which you can code your tool’s response to 

tmClearMsg. 

PROCEDURE TermToolClear( hTerm:TermHandle ); 

VAR 

theState : SignedByte; 

BEGIN 

theState ;= HGetState( Handle( hTerm) ) ; 

HLock( Handle( hTerm) ) ; 

With hTerm'^'" Do 
BEGIN 

{ erase the screen } 

EraseRect( viewRect ) ; 

{ clear up the terminal buffer } 

END; 

HSetState ( Handle(hTerm), theState); 

END; 

tmGetLineMsg 

An application will call TMGetiine when it requires your tool to send it a TermDataBiock, 
which contains the data, character attributes, and line attributes. For example, the application might 
require the data in TermDataBiock to update its cache area for a specified line. When passed to 
your tool, pi contains the line number, and p2 points to the TermDataBiock, which your 
tool should fill in. 

The sample code shows a template into which you can code your tool’s response to 
tmGetLineMsg. Your tool should fill the TermDataBiock with new information and resize 
the theTermData. theData handle for the requested line. 

PROCEDURE TermToolGetLine( hTerm:TermHandle ; lineNo:LONGINT ; 

VAR myTermBlock:TermDataBiock); 

VAR 

theState : SignedByte; 

BEGIN 

theState := HGetState ( Handle( hTerm) ) ; 

HLock( Handle( hTerm) ) ; 

With hTerm'"^ Do 
BEGIN 

myTermBlock.flags := tmTextTerminal; { this is a text terminal } 

myTermBlock.auxData := NIL; { no style information } 
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{ grow the datahandle size to fit a line of data } 
SetHandleSize( myTermBlock.theData, MAXCOL ); 

{ copy the terminal content into myTermBlock.theData } 

END; 

HSetState ( Handle(hTerm), theState); 

END; 


tmPaintMsg 

An appliation will call TMPaint when it requires your tool to display the contents of a 
TermDataBlock. When passed to your tool, pi will point to the TermOataBlock, and p2 
will point to the rectangle into which your tool is to display the line. 

If theTermData. theData is a handle to plain text (not styled), your tool can calculate the 
number of characters to paint by calling cetHandiesize. If your tool requires the data in 
theTermData after it passes control back to the calling application, it must make a copy of this 
data, since the application may change or destroy TermDataBlock. 

The sample code shows a template into which you can code your tool’s response to 

tmPaintMsg. 

PROCEDURE TermToolPaint( hTerm:TermHandle; theTermData:TermDataBlock; drawRect:Rect ) 
VAR 

theState : SignedByte; 

BEGIN 

theState := HGetState ( Handle( hTerm) ) ; 

HLock ( Handle( hTerm) ) ; 

With hTerm'^'^ Do 
BEGIN 

{ given the terminal data block, redraw those contents } 

{ within the boundaries of the given rectangle } 

END; 

HSetState ( Handle(hTerm) , theState); 

END; 

tmCursorMsg 

An application will call TMCursor when it requires your tool to pass it the current location of the 
cursor. When passed to your tool, pi will specify the type of cursor. 

The sample code shows a template into which you can code your tool’s response to 
tmCursorMsg. Your tool should retum the current cursor position. 

FUNCTION TermToolCursor( hTerm:TermHandle; cursorType: TMCursorTypes ):LONGINT; 

VAR 

theState : SignedByte; 

privatePtr : TERMINALPrivatePtr; 

BEGIN 

theState := HGetState ( Handle( hTerm) ) ; 

HLock ( Handle ( hTerm) ) ; 

With hTerm'^^ Do 
BEGIN 

privatePtr := TERMINALPrivatePtr( tmPrivate ); 
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{ return row and col if cursorType is text cursor } 

IF cursorType = cursorText THEN 

TermToolCursor ;= LONGINT( privatePtr^.tmprivatecursor) ; 

{ else return pixels if cursorType is graphic cursor } 

END; 

HSetState ( Handle(hTerm) , theState); 

END; 


tmGetEnvironsMsg 

Your tool will receive tmGetEnvironsMsg when the application has called the TMGetTermEnvirons 
routine. When passed to your tool, pi will point to the TermEnvironRec. Your tool should fill in this 
record. 

The sample code shows a template into which you can code your tool’s response to 

tmGetEnvironsMsg. 

FUNCTION TermToolGetEnvirons( hTerm:TermHandle ; 

VAR myTermEnvRec:TermEnvironRec);LONGINT; 

VAR 

theState ; SignedByte; 

privatePtr : TERMINALPrivatePtr; 

BEGIN 

theState ;= HGetState( Handle( hTerm) ) ; 

HLock( Handle( hTerm) ) ; 

With hTerm'^'^, myTermEnvRec Do 
BEGIN 

privatePtr := TERMINALPrivatePtr( tmPrivate ); 

{ return error if the given version number isn't the 
same as the current version } 

IF version > curTermEnvRecVers THEN 

TermToolGetEnvirons := envVersTooBig 
ELSE IF version < curTermEnvRecVers THEN 
TermToolGetEnvirons := envBadVers 
ELSE BEGIN 

termType := tmTextTerminal ; { it' s a text terminal } 

textRows := MAXROW; 

textCols := MAXCOL; 

cellSize.h := privatePtr^.tmprivatecellsize. h; 
cellSize.v := privatePtr^.tmprivatecellsize.v; 
slop.h := THESLOP; 
slop.v := THESLOP; 

SetRect( graphicSize, 0, 0, 0, 0 ); 

SetRect ( auxSpace, 0, 0, 0, 0 ); 

{ return no error } 

TermToolGetEnvirons := 0; 

END; 

END; 

HSetState( Handle(hTerm), theState); 

END; 
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tmEventMsg 


The Terminal Manager will pass tmEventMsg to your tool when an event occurs in a window 
associated with the terminal tool. The sample code shows a template into which you can code your 
tool’s response to tmEventMsg. When passed to your tool, pi will be a pointer to the event record. 


PROCEDURE TermToolEvent( hTerm:TermHandle ; myEventRecord:EventRecord); 

VAR 

theState ; SignedByte; 

BEGIN 

theState := HGetState ( Handle( hTerm) ) / 

HLock ( Handle( hTerm) ) ; 

With hTerm^^ Do 
BEGIN 

{ an event has been received for a window or dialog box that was } 
{ created by the terminal tool, process it accordingly. } 

CASE myEventRecord.what OF 
mouseDown: 


keyDown, autoKey; 


updateEvt: 


activateEvt: 



END; 


END; 

END; 

HSetState ( Handle(hTerm), theState); 


tmDoTermKeyMsg 

Your tool will receive tmDoTermKeyMsg when the application has called the TMooTermKey 
routine. When passed to your tool, pi will point to a string that corresponds to the key that was 
pressed. For example, if the user pressed the PFl key, the string will be “PFl.” If there is no key that 
corresponds to the string, your tool should do nothing. 

The sample code shows a template into which you can code your tool’s response to tmDoTermKeyMsg. 


PROCEDURE TermToolDoTermKey( hTerm:TermHandle ; theStr: StringPtr ); 
VAR 


theState : SignedByte; 

BEGIN 


END; 


theState := HGetState ( Handle( hTerm) ) ; 

HLock( Handle( hTerm) ) ; 

With hTerm'^'" Do 
BEGIN 

{ perform the action determined by the special 
terminal key passed in, e.g HOME, PFl etc., 

and ignore theStr if it's not recognized by the terminal tool } 

END; 

HSetState ( Handle(hTerm), theState); 
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tmCountTermKeysMsg 

Your tool will receive tmcountTermKeysMsg when the application requires your tool to pass it 
the number of special terminal key names that it supports. 

The sample code shows how your tool can respond to tmcountTermKeysMsg. 

FUNCTION TermToolCountTermKey( hTerm:TermHandle ):LONGINT; 

VAR 

theState : SignedByte; 

BEGIN 

theState := HGetState( Handle( hTerm) ) / 

HLock( Handle( hTerm) ) ; 

With hTerm'"'^ Do 
BEGIN 

{ return the number of special terminal keys 
supported by the termainl tool } 

END; 

HSetState ( Handle(hTerm), theState); 

END; 


tmGetIndTermKeyMsg 

The Terminal Manager will pass tmGetindTermKeyMsg to your tool when the application 
requires your tool to pass it the name of a special terminal key (for example, PFl, PAl, or DUP). 

When passed to your tool, pi contains the index (number) of the key. 

The code sample shows a template into which you can code your tool’s response to 
tmGetindTermKeyMsg. When your tool is done, it should pass back a pointer to a Str255 return 
value that describes the key, or a pointer to an empty string if the index is invalid. 

PROCEDURE TermToolGetIndTermKey(hTerm:TermHandle; index:INTEGER; VAR theStr:STR255) 
VAR 

theState : SignedByte; 

BEGIN 

theState := HGetState ( Handle ( hTerm) ) ; 

HLock( Handle( hTerm) ) ; 

with hTerm'^^ Do 

BEGIN 

{ return the terminal key supported by the terminal tool in theStr } 

{ or return empty string if index is out of range } 

END; 

HSetState( Handle(hTerm), theState); 

END; 
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Quick reference 


This section contains reference information for the data structures, resource names, and resource 
types that you need to write a terminal tool. A table at the end of this seaion lists all the messages 
the Terminal Manager sends to your tool, and what is passed in the parameters with each message. 

Data structures 

TMSetupStruct 

TYPE 

TMSetupPtr = ^TMSetupStruct; 

TMSetupStruct = RECORD 


theDialog 
count 
theConfig 
procID 


DialogPtr; 

INTEGER; 

Ptr; 

INTEGER 


END; 


TMSearchBlock 


TYPE 


TMSearchBlockPtr 

TMSearchBlock 


TMSearchBlock ; 
RECORD; 
StringHandle; 

Rect; 

TMSearchTypes ; 
ProcPtr; 

INTEGER; 

TMSearchBlockPtr; 



theString 

where 

searchType 
callBack 
refnum 


next 


END; 
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Resource names 


FUNCTION 

tdef(hTerm: TermHandle; 

LONGINT) : LONGINT; 

msg: 

INTEGER; 

Pl. 

P2, 

P3 

FUNCTION 

tval(hTerm: TermHandle; 

LONGINT) ; LONGINT; 

msg: 

INTEGER; 

Pl/ 

P2, 

P3 

FUNCTION 

tset(pSetup: SetupPtr; 

LONGINT) : LONGINT; 

msg: 

INTEGER; 

Pl/ 

P2, 

P3: 

FUNCTION 

tscr(hTerm; TermHandle; 

LONGINT) : LONGINT; 

msg: 

INTEGER; 

Pl/ 

P2, 

P3 

FUNCTION 

tloc(hTerm; TermHandle; 

LONGINT) ; LONGINT; 

msg: 

INTEGER; 

Pl. 

P2, 

P3 


Resource Types 


type 'tbnd' { 

integer = $$CountOf(TypeArray) - 1; 

array TypeArray { 

literal longint; /* Type */ 

integer = $$CountOf(IDArray) - 1; 
wide array IDArray { 

integer; /* Local ID */ 

integer; /* Actual ID */ 

} / 

} ; 


type 'tver' as 'vers'; 
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Table 10-1 Terminal Manager messages and parameters 
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Table 10-1 Terminal Manager messages and parameters (continued) 

Constant Parameter 1 Parameter 2 Parameter 3 
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Indicates the routine is a function that returns a longint. 







Chapter 11 Writing File-Transfer Tools 























































THIS CHAPTER tells you how to write the main code resource for a 
file transfer tool. You will need to include five other code resources as part of 
your tool; they are described in Chapter 8. You should also read that chapter, 
as well as Chapter 5, before reading this chapter. 

This chapter describes all the messages, parameters, and data structures that 
the File Transfer Manager passes to your tool’s main code resource. Also in 
this chapter is sample code (with pseudocode mixed in) that will help you 
understand what your tool should do when it receives any of the messages. A 
quick reference at the end of the chapter shows you what you should name 
your six file transfer tool resources. It also lists the messages the File Transfer 
Manager sends to your tool, and the parameters that the File Transfer 
Manager passes with each message. 
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Your £Qe transfer tool’s main code resource 

The purpose of the main code resource is to parse messages from the File Transfer Manager and 
then to branch to a routine that can handle each message. The main code resource should be a 
resource of type ' f def ' and should be able to accept the parameters shown here. 

FUNCTION fdef(hTerm; TermHandle; msg: INTEGER; pi, p2, p3: 
LONGINT) : LONGINT; 


The accepted messages are as follows: 

CONST 

ftInitMsg = 0; 

ftDisposeMsg = 1 ; 

ftSuspendMsg = 2; 

ftResumeMsg = 3; 

ftMenuMsg = 4 ; 

ftEventMsg = 5 ; 

ftActivateMsg = 6; 

ftDeactivateMsg = 7; 

ftAbortMsg = 52; 

ftStartMsg = 100; 

ftExecMsg = 102; 


For each of the messages defined above, the three parameters that »fdef* returns, namely pi, 
p2, and p3, take on different meanings. These meanings are described in the message descriptions 
that follow. Your tool can return an appropriate operating-system error code, or 
ftNotSupported if it does not understand the message it received. 

ftInitMsg 

The File Transfer Manager will pass ftInitMsg to your tool after the following sequence of 
events occurs. When a tool or application calls FTNew, the File Transfer Manager allocates space for 
the file transfer record. It then fills in some of the fields, based upon information that was passed 
in the parameters to the call. The File Transfer Manager fills in the config and oidConfig 
fields by calling FTOefauit. Then the File Transfer Manager passes ftInitMsg to your tool. 
After your tool has finished responding to ftInitMsg, the File Transfer Manager calls 
FTValidate. 

After executing the code necessary to respond to ftInitMsg, your code should pass back an 
appropriate OsErr or FTErr. Here’s an example: 

FUNCTION myInit(hFT: FTHandle); CMErr; 

VAR 

State : SignedByte; 

BEGIN 

myinit := noErr; { optimism } 

state := HGetState(Handle(hFT) ) ; { save handle state } 

HLock(Handle(hFT)); { lock it down } 

WITH hFT^^ DO 
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BEGIN 


errCode := noErr; 


{ optimism reigns } 


private := PrivatePtr(NewPtr(SIZEOF(PrivateData) )) ; 

WITH private^ DO 

BEGIN { fill in private data structure here } 

END; 

END; 

HSetState(Handle(hFT), state); 

END; 

ftDisposeMsg 

A tool or application will call FTDispose when it must dispose of a file transfer record and its 
associated data structures. 

The File Transfer Manager passes ftDisposeMsg to your tool before disposing of the 
conf ig and oidconf ig fields of the file transfer record. Next, the File Transfer Manager disposes 
of the file transfer record. 

To handle ftDisposeMsg, your tool should dispose of any buffers allocated in response to 
ftinitMsg and any private data storage (referenced off of ftPrivate in the file transfer 
record). Your tool must not attempt to dispose of either conf ig or oidConf ig in the file 
transfer record, or of the file transfer record itself. Doing so will cause a system crash. 

The sample code shows a template into which you can code your tool’s response to 

ftDisposeMsg. 

PROCEDURE myDispose(hFT: FTHandle); 

VAR 

err: FTErr; 

BEGIN 

{ abort FT in progress } 

{ do cleanup } 

DisposPtr( Ptr (hFT^'" .private) ); 

END; 

ftStartMsg 

Your tool will receive f tstartMsg from the File Transfer Manager when the application requires 
your tool to start a file transfer. The sample code shows a template into which you can code your 
tool’s response to ftstartMsg. 

Your tool should pass back the appropriate error message if unable to start the file transfer. 

FUNCTION .FTStartup(hFT: FTHandle): FTErr; 

BEGIN 

FTStart := noErr; 1 optimism } 

WITH hFT^^' DO 
BEGIN 

errCode := 0; 

flags := BOR(flags, ftIsFTMode); { file transfer in progress } 
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{ initialize the variable } 
{ open file } 

{ prepare your I/O buffer } 
{ draw the status dialog } 

END; 


END; 


ftExecMsg 

An application calls FTExec to provide time for a file transfer in progress. Your tool should strive 
to be “MultiFinder-friendly” by minimizing the time it spends handling this message. When the file 
transfer is completed, your tool should close all files and dispose of any status dialog boxes. 

PROCEDURE FTExec(hFT: FTHandle); 

BEGIN 

{ called when file transfer is in progress so do your 
stuff here...} 

END; 

ftAbortMsg 

Your tool will receive f tAbortMsg from the File Transfer Manager when the application requires 
your tool to abort a file transfer. The sample code provides a template into which you can code 
your tool’s response to ft AbortMsg. 

If your tool is unable to abort successfully, it should pass back an appropriate error code. 

FUNCTION FTAbort(hFT: FTHandle): FTErr; 

BEGIN 

{ abort the file transfer in progress here } 

{ close the file } 

{ dispose of the status dialog } 

END; 

ftActivateMsg and ftResumeMsg 

Yourt(X)l will receive ftActivateMsg or ftResumeMsg when the application requires your tool 
to process an activate event (such as inserting menus into the menu bar). The sample code shows a 
template into which you can code your tool’s response to ftActivateMsg or ftResumeMsg. 

PROCEDURE myActivate(hFT; FTHandle); 

BEGIN 

END; 

( 

pl, p2, p3 are ignored 

This routine may perform actions such as inserting a menu into the 
menu bar. 

} 


Chapter 11: Writing File Transfer Tools 281 



PROCEDURE inyResume(hFT: FTHandle) ; 

BEGIN 

END; 

{ 

pi, p2, p3 are ignored 

This routine may perform the same actions as myActivate 

) 

ftDeactivateMsg and ftSuspendMsg 

Your tool will receive ftDeactivateMsg or ftSuspendMsg when the application requires 
your tool to process a deactivate event (such as removing a menu from the menu bar) for a 
window that belongs to the File Transfer Manager. 

ftMenuMsg 

The File Transfer Manager will send ftMenuMsg to your tool when a menu event has occurred in 
the application. When passed to your tool, pi will contain the menu ID, and p2 will contain the 
menu item. 

The sample code shows a template into which you can code your tool’s response to 
ftMenuMsg . When done, your tool should pass back 0 if the menu event was not handled, and 1 if 
it was. 

FUNCTION myMenuthFT; FTHandle; mID: INTEGER; mitem: INTEGER): 

LONGINT; 

BEGIN 

myMenu := 0; { pessimism ) 

{ if mine then 

myMenu := 1; { handle the menu event ) 

} 

END; 

ftEventMsg 

Your tool will receive ftEventMsg from the File Transfer Manager when an event has occurred 
in the application. When passed to your tool, pi will point to the event record, in which the 
reference constant field contains the file transfer handle. 
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Quick reference 

This section contains reference information for the resource names, and resource types that you 
need to write a file transfer tool. A table at the end of this section lists all the messages the File 
Transfer Manager sends to your tool, and what is passed in the parameters with each message. 

Resource names 


FUNCTION 

fdef(hTerm: TermHandle; 
LONGINT) : LONGINT; 

msg: 

INTEGER; 

pi. 

p2. 

p3: 

FUNCTION 

fval(hTerm: TermHandle; 
LONGINT) : LONGINT; 

msg: 

INTEGER; 

pi. 

P2, 

p3: 

FUNCTION 

fset(pSetup: FTSetupPtr 
LONGINT) : LONGINT; 

; msg: 

: INTEGER; 

pi 

, P2 

f P3 

FUNCTION 

fscr(hTerm: TermHandle; 
LONGINT) ; LONGINT; 

msg: 

INTEGER; 

pi. 

p2. 

P3: 

FUNCTION 

floe(hTerm: TermHandle; 
LONGINT) : LONGINT; 

msg: 

INTEGER; 

pi. 

p2. 

p3: 


Resource types 

type *fbnd* { 

integer = $$CountOf(TypeArray) - 1; 
array TypeArray { 

literal longint; /* Type */ 

integer = $$CountOf(IDArray) - 1; 
wide array IDArray { 

integer; /* Local ID */ 

integer; /* Actual ID */ 

}; 

}; 

}; 
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Table 11-1 File Transfer Manager messages and parameters 
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Indicates the routine is a function that returns a longint. 









Appendix A Guidelines for Communications Tools 


THIS APPENDIX contains software design and human interface 
guidelines for communications tools. The guidelines presented in this 
appendix, while not hard-and-fast rules, will help ensure that your tool works 
with future releases of the Communications Toolbox, with other tools, and 
with applications that use the Communications Toolbox. 

This appendbc discusses the design goals your tool should implement. Then it 
discusses human interface considerations. Finally, the appendix describes 
hardware and software compatibility requirements. 

To fully understand this appendix, you should first read Chapter 8, 
“Fundamentals of Writing Your Own Tool,” and at least one of the following 
chapters: Chapter 9, “Writing Connection Tools”; Chapter 10, “Writing 
Terminal Tools”; or Chapter 11, “Writing File Transfer Tools.” 



Design goals 

when you design your tool keep these goals in mind. Your tool should be 

■ Self-contained: It should contain all the resources it needs in its bundle resource, and not need 
to make use of other tools or applications. 

■ Task-spedfic: It should be a connection tool, a terminal tool, or a file-transfer tool. It should 
respond to all the messages that the manager sends to it, but not to any messages that a 
Communiations Toolbox manager intends a different tool to respond to. For instance, a 
terminal tool should not respond to Connection Manager messages and should not implement 
or maintain a data connection. 


Keeping your tool self-contained 

For users, installing a communications tool should be as simple as dragging the icon for that tool 
into the folder named Communications Folder on the desktop. To achieve this level of simplicity, 
your tool must be self-contained; all the resources it needs for proper operation must be in the 
resource bundle. 

There are, however, two exceptions to this principle. The first is when your tool uses a 
hardware interface that requires a driver to be loaded at INIT time, an unavoidable circumstance. 
The second exception is when your tool provides access to special data files (for example, a file of 
network addresses) that are kept on the user’s system. Such data files provide your tool with a 
convenient way to store and distribute configuration information. In such a case, your tool should 
save all user settings in the session document; your tool must not require external files to 
reestablish a previously configured connection. Whenever your tool does require an external file to 
operate properly, it should check for the existence of that file and notify the user if the file is not 
present. 

To prevent resource ID conflicts, your tool should use resource IDs that are out of the range of 
IDs that Apple’s system resources use. Even when taking this precaution, font IDs may conflict. 
The only sure way to avoid this is to register your font IDs with Developer Technical Support. This 
problem arises because your tool’s resource map gets linked into the resource chain, while your 
tool’s code is executing, just below the system file’s resource map. 


Keeping your tool task-specific 

The Communications Toolbox supports three kinds of communications tools: connection, terminal, 
and file transfer. Your tool should be one of these types and must not implement any services that 
another type of tool is intended to provide. For instance, if you are writing a terminal tool, it must 
not provide any connection services. Observing this principle helps ensure that tools will not 
interact with each other in unintended ways. Each type of tool is meant to provide specific services: 
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■ Connection tools control the data path and its specifications. They can also alter the data path 
or strip high bits, as needed. 

■ Terminal tools control user input and output, including input from the mouse or keyboard, and 
output to the terminal emulation window. 

■ File-transfer took control sending and receiving dkk files, or other encapsulated data entities. 
Only file-transfer tools should manipulate dkk files or the file system. 

Took written for the Communications Toolbox are meant to be used in a way that enables users to 
change one part of a communications configuration and still have the application work for them. 
For instance, a user running a VTIOO™ terminal emulation over a modem connection should be able 
to run the emulation over an X.25 connection and not notice any changes. 

However, if a terminal or file-transfer tool requires a specific type of connection (because of the 
protocol or standard being implemented) that k not in place, your tool should send an error to the 
application. A tool must never cause a system-level error when a user tries to use it in the “wrong” 
configuration. Rather, it should detect the presence or absence of a tool and send appropriate return 
codes to the application. 

When writing a tool to implement an exkting communications standard, you might find that 
the functions included in the standard require more than one type of tool for implementation. In 
cases like thk, try to keep your tool task-specific by making use of the Macintosh interface. For 
example, if a connection protocol requires that your tool have status information constantly 
available, your tool can dkplay thk information in a separate window. You can also implement the 
standard by writing two task-specific took that must be used together. 


User interface considerations 

Thk section describes the user interface considerations you should keep in mind when designing 
your tool. These considerations include 

■ modeless tool operation 

■ the standard tool-settings dialog box 

■ windows and status dialog boxes 

■ error alerts 

■ menus 

■ handling errors 

■ using the right words 
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Modeless tool operation 

Your tool should be modeless because the Communications Toolbox (and most applications that use 
it) allows for multiple simultaneous communications sessions; your session may not be the only one 
running (and your tool may be in use in more than one session at a time). Also keep in mind that even 
if the user is running a single session, he or she may be running that session under MultiFinder. 

Although specific applications can present other user interfaces, the user will usually configure a 
tool from within an application by using the standard tool-settings dialog box, open or close the 
connection with menu items, and send or receive files with menu items. This dialog box and the menus 
are the basic aspects of the user interface. 

The user will usually create a new document, configure it by using the standard tool-settings 
dialog box, and save it. Your tool should save all user settings in the session file, typically in a separate 
resource for each of the communiations tool types (connection, terminal, and file transfer). The 
design of the Communications Toolbox assumes that the application will save settings in session 
documents so that a user can use a preconfigured document to open a connection. A user who uses 
several setting combinations is expected to prepare and use a separate document for each combination. 

Users should not need to perform more configuration tasks when they open a connection or 
transfer a file; the only dialog boxes that should appear at this time are status dialog boxes. Therefore, 
your tool should fill in appropriate default settings when it is first selected in the standard tool- 
settings dialog box. 


The standard tool-settings dialog box 

Since users can use different tools inside the same application, the standard tool-settings dialog box 
for each tool ought to be visually compatible with those of other tools. This compatibility allows 
users to apply what they learn about configuring one type of tool to configuring a second type of 
tool. Figure A-1 shows a sample tool-settings dialog box for a connection tool. 

■ Fig[ure A-1 A sample tool-settings dialog box for a connection tool 
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Many communications tools require more parameters set by the user than can be displayed 
attractively in a modal dialog box the size of the Macintosh Plus screen. Consider having your tool 
use 9-point Geneva for tool controls, instead of 12-point Chicago. 

If your tool is complex and requires more controls than can fit in a modal dialog box even when 
using 9-point Geneva, it can divide these controls among two or more dialog boxes. The controls 
should be grouped according to function. Your tool should place the controls a user is most likely to 
select in the first dialog box displayed when the standard tool-settings dialog box comes up; it 
should place “power user” controls in subsequent dialog boxes. 

Since the standard tool-settings dialog box is modal, your tool should not use additional modal 
dialog boxes that pop up on top of the standard tool-settings dialog box. If your tool requires a 
cascading dialog box, it should use dialog boxes like sFGetFiie, which controls settings that do 
not usually need to be changed. Your tool should never display more than two layers of modal 
dialog boxes on the screen at the same time. 


Windows and status dialog boxes 

The terminal window is the only window that any of the communications tools displays during 
normal operation. But a connection or file-transfer tool might need to pass information to the user. 
Since these tools should not place text in the terminal window, such a tool should display its own 
window or modeless dialog box. 

Display of status dialog boxes is the most common method tools use to request input or 
display output. When a tool performs an operation that will take a long time—^for example, 
transferring a file or establishing a complex connection—the tool should post a status dialog box. 
This status dialog box should have the following characteristics: 

■ It should be modeless. 

■ It should contain a Cancel button to allow the user to stop the operation. Use of the 
Command-period key combination for cancellation is problematic because multiple sessions 
may be running; users could inadvertandy cancel dialog boxes other than the one they intended 
to cancei, by pressing the Command-period key combination severai times. 

Figure A-2 shows an example of a file-transfer tool status dialog box. 


Figure A-2 Example file-transfer tool status dialog box 


File Transfer Status 


Sending tent file “tenttest". 


0 10 20 30 40 50 60 70 00 90 100% [ Cancel 
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A tool might also put up its own window for user input and output during a session. For example, a 
connection tool might provide a command window that allows users to type in commands direcdy 
to control the connection. Your tool should either display this kind of window when the 
application initially selects your tool, or install a custom menu item that toggles in a manner similar 
to Hide Clipboard/Show Clipboard. Keep in mind that all command functions should be available 
through standard Macintosh controls, such as menu items and configuration dialog box settings. If 
your tool displays a command-line mode for compatibility with an existing standard, the 
command-line mode should supplement the standard Macintosh interface rather than replacing it. 


Error alerts 

Your tool is responsible for informing users of significant error conditions if the cmQuiet or 
f tQuiet bit is not set in the connection record or file transfer record. For instance, a connection 
tool should provide the user with status information when opening or closing a connection, and a 
file transfer tool should report the success or failure of a file transfer. However, a tool should not 
report less critial information, for example, showing a message when reading or writing data. 


Menus 

Your tool can place a menu of its own in the menu bar of the application. However, it should avoid 
displaying such menus, because the menu bar has limited available space, and appliation designers 
tend to assume that they can use the entire menu bar. Also, since up to three tools can be aaive at 
once, up to three tool menus might be displayed in addition to the menus owned by the 
application. If you do choose to implement a menu for your tool, choose a menu name that is as 
short as possible to avoid overflowing the menu bar. 

Tool-specific menus are placed to the right of application menus. This means that if the menu 
items of your tool have Command-key equivalents, they will override any conflicting Command- 
key equivalents for application menus. If two tool menus are displayed at the same time, the 
rightmost menu will override the other in a similar fashion. Also, your application should not have 
any Command-key equivalents for non-ADB (Apple Desktop Bus™) keyboards; conflicts can arise 
out of the need to use the Control key as a Command key. 


Handling errors 

Your tool should allow users to set up any communications configuration, even ones that are 
unuseable. This allows a system administrator to configure and save a session document for 
another person, who uses a different configuration from that on the system administrator’s 
machine. In such cases, your tool should return an error only if the user attempts to open a 
connection, start terminal emulation, or initiate a file transfer using a setup that won’t work. 
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Using the right words 

Macintosh developers normally use terms that are intuitive and easy to learn, even for naive users. 
However, this practice sometimes conflicts with the need to use established industry-standard 
terms, which may be difficult for the novice to understand Since communications software 
developers often implement preexisting industry standards, this problem is especially common for 
developers of communications tools. 

Where standard terms for a function already exist and are widely accepted in the industry, you 
an use the standard terms. This convention is meant to ensure both that your tool properly 
implements the standard, and that experienced communiations users who are familiar with the 
standard terms are not confused. However, you should attempt to make these terms as easily 
understandable as possible for inexperienced users. You an do this in several ways. Alternate 
standard terms are sometimes available. For example, the term Show ContrcJs ind its less-intuitive 
counterpart Transparent Mode are used by Digital Equipment Corporation for the same VT102™ 
terminal setting. You might also be able to embed the standard term in a longer description, or use 
small graphia in the tool-settings dialog box to make manings clearer. 


Compatibility requirements 

The Communiations Toolbox an run on all Macintosh computers that have: 

■ at last 1 MB of RAM 

■ Macintosh Plus (128K) ROM, or later versions 

■ system software version 6.0.4, or a later version 

In order to be compatible with future relases of system software, it is important that your tool 
be 32-bit clean. Your tool may have additional requirements or restrictions. 


Keyboard considerations 

Terminal tools should support all Macintosh keyboards, including the classic Macintosh keyboard 
with and without the detatchable keypad. If arrow keys, function keys, the Control key, or other 
keys are required by your tool but are not on all keyboards, your tool should provide an alternative 
means of accessing them. Your tool could provide a keypad menu, or allow the user to use the 
Command key as a Control key. 
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Appendix B Usefiil Code Samples 


THIS APPENDIX shows you solutions to common programming 
problems; 

■ implementing effective idle loops 

■ determining events that need to be handled by one of the Communications 
Toolbox managers 

■ customizing the tool-settings dialog box 

■ determining whether the Communications Toolbox managers are installed 



Using FTExec and TMidie effectively 

The following code sample shows when your application needs to call FTExec and TMidie during a file transfer. 

PROCEDURE Doldle; 

VAR 

theWindow 
doFT 
doTM 

savedPort 

BEGIN 

GetPort(savedPort); 
theWindow := FrontWindow; 

{ Give idle time for the window } 

WHILE (theWindow <> NIL) DO BEGIN 
(* 

Make sure the window belongs to the application 
*) 

SetPort(theWindow); { Focus on it } 

IF gConn <> NIL THEN { Give time to the connection } 

CMIdle(gConn); 

doFT := FALSE; 
doTM := TRUE; 

IF gFT <> NIL THEN BEGIN 

{ Is there a file transfer in progress ?? } 

IF BAND (gFT'^'^. flags, ftIsFTMode) <> 0 THEN BEGIN 

doFT := TRUE; 
gWasFT ;= TRUE; 

{ If the FT tool uses my connection then } 

{ don’t route data to the terminal tool } 

IF BAND (gFT'"'^. attributes, ftSameCircuit) <> 0 THEN 

doTM := FALSE; 

END { In progress } 

ELSE BEGIN 

IF gWasFT THEN BEGIN 

{ FT no longer in progress } 
gWasFT := FALSE; 

{ if it failed, alert } 

IF BAND (gFT'"'". flags, FTSucc) = 0 THEN 
; { Handle error } 


{ Send data to FT tool } 

{ Send data to terminal tool } 


{ Save for later } 

{ Gimme the first one } 


WindowPtr; { 
BOOLEAN; { 
BOOLEAN; { 
GrafPtr; { 


The target to idle } 
route data to FT Tool } 
route data to Term Tool } 
for later reset } 


(* 


294 Macintosh Communications Toolbox Reference 





Re-add the file transfer auto-receive string 
that was removed at FTStartO 
*) 


END; 


{ AutoReceive string was received? } 

IF gStartFT THEN 
DoReceive; 

END; { No FT in progress } 

IF doFT THEN { Give time to FT tool } 

FTExec(gFT); 

END; { Good FT Handle } 

IF gTerm <> NIL THEN BEGIN 

{ Send data to terminal } 

IF doTM THEN BEGIN 

TMIdle (gTerm) ; { So it can blink its cursor, etc } 

TermRecvProc; { Send Data to the terminal } 

END; { Send data to terminal } 

END; { Good Terminal } 


{ Try the next window } 

theWindow := WindowPtr (WindowPeek (theWindow). nextWindow) ; 


END; { while each window } 

SetPort(savedPort); { Back to the way it was } 

END; { Doldle } 

PROCEDURE TermRecvProc; 

VAR 

theErr : CMErr; 

status : CMStatFlags; 

sizes : BufferSizes; 

flags : INTEGER; 

BEGIN 

IF (gConn <> NIL) AND (gTerm <> NIL) THEN BEGIN 

{ Get the state of the connection } 

theErr := CMStatus(gConn, sizes, status); 

IF (theErr = noErr) THEN BEGIN 


{ Any errors } 

{ For the conn tool } 


{ Route the data if we have any } 
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IF (BAND(status, cmStatusDataAvail) <> 0) AND 
(sizes [cmDataIn] <> 0) THEN BEGIN 

{ Don't overflow my buffer } 

IF sizes[cmDataIn] > kBufferSize THEN 
sizes[cmDataIn] := kBufferSize; 

{ Tell the tool to get the data } 

theErr := CMRead(gConn, gBuffer, sizes[cmDataIn], 
cmData, FALSE,NIL,0, flags) ; 

{ Send data to the terminal } 

IF (theErr = noErr) THEN 

sizes[cmDataIn] := TMStream(gTerm,gBuffer, 

sizes[cmDataIn],flags) 


END; { sizes <> 0 } 

END; { Good Status } 

IF (theErr <> noErr) THEN 

AlertUser('Couldn''t send data to terminal*,FALSE); 
END; { Good term & conn } 

END; { TermRecvProc } 
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Determining events for Communications Toolbox managers 

The following routines show how an application can determine if an event needs to be handled by 
one of the Communications Toolbox Manager event-processing routines. 


FUNCTION 
VAR 

pWindow: 
tempFT; 
hFT: 


IsFTWindow(theWindow: WindowPtr): BOOLEAN; 

WindowPtr; 

FTHandle; 

FTHandle; 


BEGIN 


END; 


IsFTWindow := FALSE; 

IF WindowPeek (theWindow).windowKind <> dialogKind THEN 
Exit(IsFTWindow); 

tempFT := FTHandle(GetWRefCon(theWindow) ) ; 

pWindow := FrontWindow; 

WHILE pWindow <> NIL DO 
BEGIN 

hFT := GethFT(pWindow); 

IF hFT <> NIL THEN 
BEGIN 

IF LONGINT(hFT) = LONGINT(tempFT) THEN 
BEGIN 

IsFTWindow := TRUE; 

Exit(IsFTWindow); 

END; 

END; 

pWindow := WindowPtr(WindowPeek(pWindow)^.nextWindow); 
END; 


FUNCTION IsFTEvent(theEvent: EventRecord): FTHandle; 
VAR 

theWindow : WindowPtr; 

hFT : FTHandle; 


BEGIN 


IsFTEvent := NIL; 
theWindow := NIL; 


CASE theEvent.what OF 

autoKey, keyDown: 

BEGIN 

theWindow ;= FrontWindow; 
END; 
mouseDown: 


{ no Command-key equivalents on a Macintosh Plus } 
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BEGIN 

IF FindWindow(theEvent.where, theWindow)=0 THEN 


END; 
updateEvt: 

BEGIN 

theWindow ;= WindowPtr(theEvent.message); 
END; 

activateEvt: 

BEGIN 

theWindow := WindowPtr(theEvent.message) ; 
END; 

END; {case} 

IF theWindow <> NIL THEN 
BEGIN 

IF IsFTWindow(theWindow) THEN 
BEGIN 



hFT : * FTHandle(GetWRefCon(theWindow)); 

IsFTEvent :* hFT; 

END 

ELSE 

BEGIN 

hFT : = GethFT(theWindow); 

IF hFT <> NIL THEN 

BEGIN 

IF BAND (hFT'"'". flags, FTIsFTMode) <> 0 THEN 

IF BAND (hFT'"'". attributes, 

FTSameCircuit) <> 0 THEN 

IF theEvent.what IN 

[autoKey, keyDown] THEN 

IsFTEvent := hFT; 

END; 

END; 

END; 

END; 



{$S EventSeg} 

FUNCTION IsConnEvent(theEvent: EventRecord): ConnHandle; 


VAR 


theWindow 

: WindowPtr; 

hConn 

: ConnHandle; 

BEGIN 


IsConnEvent 

:= NIL; 

theWindow ;= 

NIL; 


CASE theEvent.what OF 

autoKey, keyDown: { no Command-key equivalents on a Macintosh Plus } 

BEGIN 

theWindow ;= FrontWindow; 
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END; 
mouseDown: 

BEGIN 

IF FindWindow(theEvent.where, theWindow)=0 THEN 


t 


END; 


updateEvt: 

BEGIN 


theWindow := 

WindowPtr(theEvent.message); 

END; 

activateEvt: 


BEGIN 


theWindow := 

WindowPtr(theEvent.message); 

END; 


END; {case} 


IF theWindow <> NIL THEN 



BEGIN 

IF IsConnWindow(theWindow) THEN 
BEGIN 

hConn ;= ConnHandle(GetWRefCon(theWindow)); 


IsConnEvent : 

= hConn; 

END; 


END; 


END; 


{$S EventSeg} 



FUNCTION IsTermEvent(theEvent: EventRecord): TermHandle; 

VAR 

theWindow : WindowPtr; 

hTerm ; TermHandle; 

BEGIN 

IsTermEvent := NIL; 
theWindow := NIL; 

CASE theEvent.what OF 

autoKey, keyDown: { no command-key equivalents on a Mac plus } 


BEGIN 


theWindow := 

FrontWindow; 

END; 


mouseDown: 



BEGIN 

IF FindWindow(theEvent.where, theWindow)=0 THEN 


/ 


END; 

updateEvt: 

BEGIN 


theWindow := 

WindowPtr(theEvent.message); 

END; 

activateEvt; 


BEGIN 
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theWindow := WindowPtr(theEvent.message); 
END; 

END; {case} 

IF theWindow <> NIL THEN 
BEGIN 

IF IsTermWindow(theWindow) THEN 
BEGIN 

hTerm := TermHandle(GetWRefCon(theWindow)); 
IsTermEvent := hTerm; 

END; 


PROCEDURE MainLoop; 
VAR 

theEvent 

theWindow 

theWindowPeek 

theControl 

savedPort 

theKey 


EventRecord; 

WindowPtr; 

WindowPeek; 

ControlHandle; 

GrafPtr; 

CHAR; 


processed 

result 

hFT 


BOOLEAN; 

LONGINT; 

FTHandle; 


BEGIN 

WHILE NOT done DO 
BEGIN 

SystemTask; 


Doldle; { application idle loop procedure } 

IF WaitNextEvent(everyEvent,theEvent, 0, NIL) THEN 

BEGIN 

hFT := IsFTEvent(theEvent); 

IF hFT <> NIL THEN 

FTEvent(hFT, theEvent) 

ELSE 

BEGIN 

CASE theEvent.what OF 

autoKey, keyDown: 

DoKey(theEvent); 
mouseDown; 

DoClick(theEvent); 
updateEvt: 

DoUpdate(theEvent) ; 
app4Evt: 

DoResume(theEvent) ; 
activateEvt: 
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END; 


END; 

END; 

END; { gne } 

END; { if done } 


DoActivate(theEvent); 
{ case } 
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The custom tool-settings dialog box 

The sample code that follows shows how your application can use Connection Manager routines to 
present the user with a custom tool-settings dialog box. 

Choose.P 

This performs the standard dialog box for configuration and selection of a Connection tool. 


CONST 

ChooseltemOK 

r= 

1; 

{ 

Location of Dialog Box Items } 


ChooseItemCancel 

= 

2; 




ChooseltemPopup 

= 

5; 




ChooseResourceBase 

= 

256; 



TYPE 

dialoginfoP 


^dialoglnfo; 

{ 

storage private to the config dialog box} 


dialoginfo 

s 

RECORD 




tempProcID 

: 

INTEGER; 

{ 

MUST be the first item in record } 


magicCookie 

5 

LONGINT; 

{ 

MUST be the second item in the record } 


tempConfig 

: 

Ptr ; 

{ 

config record being used - 

these are needed by the filter proc } 


count 

; 

INTEGER; 




FUNCTION ChooseEntry(VAR theHandle: ConnHandle; where: Point): INTEGER; 

{ theHandle is the current connection handle. 

where is the upper-left corner of the selection dialog box. } 


VAR 

maxExtent : Rect; 
oldSize : Point; 


{ max size of dialog box in global oordinates 
{ old size of dialog box before resizing } 


savedPort 
theWindow 
theDialog 
infoP : 


GrafPtr; 
WindowPtr; 
DialogPtr; 
dialoginfoP; 


{ saved port } 

{ for invalidating after DisposDialog } 
{ the choose dialog box} 

{ pointer to dialog data } 


tempTool : Str255; { currently selected tool name } 

oldName : Str255; { initially selected tool name } 


theControl : ControlHandle;{ Pop-up Control } 

hMenu : MenuHandle; { handle to popup menu control's menu } 

theltem : INTEGER; { for manipulating dialog box items } 
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itemKind ; 

itemHandle 

itemRect : 

INTEGER; 

: Handle; 

Rect; 



thePtr : 

configSize 

Ptr; 

: LONGINT; 

{ ptr to temporary configuration record 

{ Size of the congiguration record } 


oldVal : 

newVal : 

INTEGER; 

INTEGER; 

{ old pop-up menu value } 

{ current pop-up menu value } 


hDITL : 

Handle; 

{ handle to DITL to append } 

Label 

theErr : 

1; 

OSErr; 

{ for building list of tools } 

{ Cleanup } 

BEGIN 





ChooseEntry ;= ChooseFailed; { pessimistic } 

InitCursor; { reset to arrow } 

GetPort(savedPort); 


theDialog := nil; 
infoP := nil; 

theDialog := GetNewDialog(chooseResourceBase, NIL, POINTER(-1)); 
IF theDialog = NIL THEN { unsuccesful } 

Goto 1; {Go Cleanup } 


SetPort(theDialog); 

infoP := dialogInfoP(NewPtr(SIZEOF(dialoginfo))); 
IF infoP = NIL THEN { 

Goto 1; { 

SetWRefCon(theDialog, LONGINT(infoP)); { 


{ internal data space 
no memory } 

Go Cleanup } 

set the refcon to infoP 


} 


WITH infoP'" DO 
BEGIN 

count := CountDITL (theDialog) ; { # items in DITL } 


tempProcID := theHandle^'".procID; { get the tool procID } 

CMGetToolName(tempProcID, tempTool); { get the toolname } 

oldName tempTool; { save the toolname } 


thePtr := theHandle^^.config; 
configSize := GetPtrSize(thePtr); 


{ get the config field } 

{ get size of config record } 
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IF MemError <> noErr THEN 

{ memory problem } 

Goto 1; 

{ Go Cleanup } 

tempConfig := NewPtr(configSize) ; 

{ copy it if possible... } 

IF tempConfig = NIL THEN 

{ didn * t get it } 

Goto 1; 

{ Go Cleanup } 


BlockMove(thePtr, tempConfig, configSize); { copy it } 

{ set up pop-up menu } 

theControl := GetNewControl(chooseResourceBase, theDialog); 


IF theControl = NIL THEN 


Goto 1; 

{ Go Cleanup } 


hMenu := GetMHandle(chooseResourceBase) ; 
IF hMenu = NIL THEN 


Goto 1; 

{ Go Cleanup } 

{ Enter all of the connection tools into the 

pop-up menu } 

theltem := 1; 



theErr := noErr; 


WHILE theErr = noErr DO 

{ while no problems } 

BEGIN 



theErr ;= CRMGetIndToolName( ClassCM, theltem, tempTool); 


IF theErr = noErr THEN 

{ no problems ociffer } 

BEGIN 


IF tempTool <> ' ' THEN 

{ got one! } 

BEGIN 



{ Orig. tool? Case INsens, Diacrit sens } 

IF Equalstring(tempTool, oldName, FALSE, TRUE) THEN 
oldVal := theltem; 

AppendMenu(hMenu, 'X'); 

{ this is to prevent problems with special 
menu characters, like /} 

Setitem(hMenu, theltem, tempTool); 


{ get the next one 

theltem := theltem 

please } 

+ 1; 

END; 


END; 


END; {while} 


theltem := theltem - 1; 

{ One too many above } 

IF OldVal = 0 THEN 

{ Current tool not in menu } 
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BEGIN 


{ The user has moved the file out of the communications 
directory - we can show the name, but this menu item 
needs to be disabled } 

theltem := theltem +1; { Update these counts } 

oldVal := 1; 

InsMenuItem(hMenu, 'X', 0); 

Setitem(hMenu,oldVal,oldName); 

Disableltem(hMenu, oldVal); { disable it } 

END; 

SetCtlMax (theControl, theltem); { max of ctl *= num tools} 

{ fix rectangle size in case of control resize } 

GetDItem(theDialog, ChooseltemPopup, itemKind, itemHandle, itemRect); 
itemRect := theControl'^'^. contrlRect; 

SetDItem(theDialog, ChooseltemPopup, itemKind, itemHandle, itemRect); 
oldSize := theDialog^.portRect.botRight;{ old size of dialog box) 
newVal := oldVal; 

SetCtlValue(theControl, oldVal); { set up pop-up value } 

{ get DITL to append } 

hDITL := CMSetupPreflight(tempProcID, magicCookie); 

{ 

Set the dialog's text info based on 
the tool's finf resource 

} 

AppendDITL(theDialog, hDITL, appendDITLBottom); { append it } 

IF hDITL <> NIL THEN { done with the DITL } 

DisposHandle(hDITL); 


{ set up the items } 

CMSetupSetup(tempProcID, tempConfig, count+1, theDialog, magicCookie) 

MoveWindow(theDialog, where.h, where.v, TRUE); { move dialog box } 
ShowWindow(theDialog) ; 

{Get dialog box size} 

maxExtent := WindowPeek (theDialog) . strucRgn'"'". rgnBBox; 
theltem 0; 

WHILE (theltem <> ChooseltemOK) AND (theltem <> ChooseltemCancel) DO 
BEGIN 

ModalDialog(QChooseFilter, theltem); { modal dialog box} 

IF theltem = ChooseltemPopup THEN { did pop-up get hit? } 

BEGIN 

{ what is new value? } 
newVal ;= GetCtlValue(theControl); 
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IF newVal <> oldVal THEN 
{ it has changed! } 

BEGIN 

{ cleanup the setup } 

CMSetupCleanup(tempProcID, tempConfig, count+1, 
theDialog, magicCookie); 
ShortenDITL(theDialog, 

CountDITL(theDialog) - count); 

{ done with tool } 

CMSetupPostflight(tempProcID); 

{ reset size } 

SizeWindow(theDialog, oldSize.h, 
oldSize.v, TRUE); 


{ get new tool name } 

Getitem(hMenu, newVal, tempTool); 

{ get procID } 

tempProcID := CMGetProcID(tempTool); 


hDITL := CMSetupPreflight(tempProcID, 

magicCookie); 


{ new DITL } 


{ 

Set the dialog box's text info based on 
the tool's finf resource 

} 


{ append it } 

AppendDITL(theDialog, hDITL, appendDITLBottom); 

IF hDITL <> NIL THEN 

{ get rid of it } 

DisposHandle(hDITL); 

{ get rid of old config } 

DisposPtr(tempConfig); 

tempConfig := NIL; { pessimistic } 

{ and get a new one } 

CMDefault(tempConfig, tempProcID, TRUE); 
if tempConfig = NIL then 

BEGIN { Clean up from error} 

ShortenDITL(theDialog, 

CountDITL(theDialog) - count); 
CMSetupPostflight(tempProcID); 

{ Out of memory } 
chooseEntry := chooseFailed; 

Goto 1; { Finish cleanup } 

END; 

CMSetupSetup(tempProcID, tempConfig, count+1, 

{ set up the items } 
theDialog, magicCookie); 
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oldVal := newVal; { Now the old tool } 
UnionRect(maxExtent, 

WindowPeek (theDialog) . strucRgn'^'^. rgnBBox, 
maxExtent); {grow max size} 

END; 

END; (item = count } 


IF theltem > count THEN { tool's item hit } 

CMSetupItem(tempProcID, tempConfig, count+1, theDialog, 
theltem, magicCookie); 

END; (while theltem NOT OK or Cancel} 


HideWindow(theDialog); 
newVal := GetCtlValue(theControl) ; 
Getitem(hMenu, newVal, tempTool); 
tempProcID := CMGetProcID(tempTool); 


{ hide the dialog box } 
{ check name change} 

{ get the new name } 


{ Clean out the old tool } 

CMSetupCleanup(tempProcID, tempConfig, count+1, theDialog, magicCookie) 
ShortenDITL(theDialog, CountDITL(theDialog) - count); 

CMSetupPostflight(tempProcID); 


IF theltem = ChooseltemOK THEN 

BEGIN { has the name of tool changed? } 

IF NOT Equalstring(oldName, tempTool, FALSE, TRUE) THEN 
BEGIN 

ChooseEntry := ChooseOKMajor; 
tempProcID := CMGetProcID(tempTool); 

IF NOT DoNewConn(ConnHandle(theHandle), tempProcID, 
tempConfig) THEN 
ChooseEntry := ChooseAborted; 

IF theHandle = NIL THEN { disaster! } 

ChooseEntry := ChooseDisaster 

ELSE 

BEGIN 

configSize := GetPtrSize(tempConfig); 

BlockMove(tempConfig, 

theHandle'"'^. config, configSize) ; 

{ validate for kicks } 

IF CMValidate(theHandle) THEN 
END; 

END 

ELSE 

BEGIN { same tool, so validate } 

ChooseEntry := ChooseOKMinor; 
configSize := GetPtrSize(tempConfig); 

BlockMove (tempConfig, theHandle''^ . config, configSize); 
IF CMValidate(theHandle) THEN 
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END; 

END 

else { user hit CANCEL } 

ChooseEntry := ChooseCancel; 

{ now we need to go through window list and update all areas that were ever 
covered up by the config dialog box which has grown and potentially shrunk. 

We have kept track of the largest size of the dialog box. we will now convert 
it to local coords and invalrect everybody in the window list } 
theWindow := FrontWindow; 

WHILE theWindow <> NIL DO 
BEGIN 

SetPort(theWindow); 
itemRect := maxExtent; 

{ get max extent in local coords } 

GlobalToLocal(itemRect.topLeft); 

GlobalToLocal(itemRect.botRight) ; 

InvalRect(itemRect); 

theWindow WindowPtr ( WindowPeek (theWindow). nextWindow ); 

END; 

END; { with } 

1: { Clean everything up } 

IF theDialog <> nil THEN DisposDialog(theDialog); 

IF infoP <> nil THEN 
BEGIN 

IF infoP'^. tempConfig <> nil THEN DisposPtr (infoP^ . tempConfig) ; 
DisposPtr(Ptr(infoP)); 

END; 

SetPort(savedPort); { back to original port } 

END; 

{ change from one connection type to another } 

FUNCTION DoNewConn(VAR hConn:ConnHandle; tempProcID:INTEGER; 

tempConfig:Ptr) : BOOLEAN; 

VAR 


savedDesiredSizes 

BufferSizes; 

savedRefCon 

. LONGINT; 

savedUserData 

LONGINT; 

savedFlags 

LONGINT; 

savedReservedO 

LONGINT; 

savedReservedl 

LONGINT; 

savedReserved2 

LONGINT; 

status 

LONGINT; 

sizes 

BufferSizes; 

theErr 

CMErr; 


BEGIN 

theErr CMStatus(hConn, sizes, status); { get conn status } 

IF theErr = noErr THEN { OK } 
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IF BAnd(status, CMStatusOpen+CMStatusOpening) <> 0 THEN 

r 

{The connection is open - confirm if the user really wants to close the connection 
setting result to FALSE if user aborts} 


WITH hConn'"'^ DO { save all desired parameters } 

BEGIN 

savedFlags := flags; 
savedDesiredSizes := BufSizes; 
savedRefCon := refcon; 
savedUserData ;= userData; 
savedReservedO := reservedO; 
savedReservedl := reservedl; 
savedReserved2 := reserved2; 

END; 


CMDispose (hConn); 


{ get rid of old conn } 


hConn := CMNew(tempProcID, savedFlags, savedDesiredSizes, savedRefCon, 
savedUserData); 

IF hConn <> NIL THEN 

WITH hConn'"^ DO BEGIN { Restore other fields } 

reservedO := savedReservedO; 
reservedl := savedReservedl; 
reserved2 := savedReserved2; 

END; 

DoNewConn := TRUE; 

END; 


{ Choose dialog box filter procedure } 

FUNCTION ChooseFilter(theDialog : DialogPtr; VAR theEvent:EventRecord; 

VAR theltem:INTEGER) : BOOLEAN; 


VAR 


theControl 

where 

result 

theKey 


ControlHandle; 
Point; 

BOOLEAN; 

CHAR; 


savedPort 

theWindow 


GrafPtr; 
WindowPtr; 


{ for event processing } 


pDialogInfo 


DialoginfoP; 


{ dialog box private data } 


BEGIN 

theltem := 0; 
result := FALSE; 


{ nothing initially } 
{ for now... } 


pDialogInfo := DialoginfoP(GetWRefCon(theDialog)); { get the dlog data } 

WITH pDialogInfo'" DO 

BEGIN 

result := CMSetupFilter(tempProcID, tempConfig, count+1, theDialog, 

theEvent, theltem, magicCookie); 
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ChooseFilter :* 
IF result THEN 


result; 


END; 


Exit(ChooseFilter); 


{ TRUE or FALSE } 

{ it WAS processed } 
{ so exit } 


CASE theEvent.what OF { process the event } 

updateEvt: 

BEGIN 

GetPort(savedPort); { get the port } 

theWindow := WindowPtr(theEvent.message); 

{ get the update owner } 

SetPort(theWindow); 

BeginUpdate(theWindow); 

EraseRect(theWindow^.portRect); { erase } 


IF theWindow * theDialog THEN { process if ours } 
UpdtDialog (theDialog, theWindow'^. visRgn) ; 


EndUpdate(theWindow); 
SetPort(savedPort); 
result := TRUE; 

END; 

mouseDown: 

BEGIN 

where := theEvent.where; 
GlobalToLocal(where); 


{ otherwise eat it } 

{ We regenerate updates when 
we have finished choosing } 


{ where was the mouse-down } 
{ convert to local coords } 


IF FindControl(where, theDialog, theControl) <> 0 THEN 

{Click in control?} 

BEGIN 

IF TrackControl(theControl, 

where, POINTER(-l)) <> 0 THEN 
{ track it } 

BEGIN 

result := TRUE; { we got the event } 

theltem FindDItem(theDialog, where) + 1; 

{ so item hit } 

END 

ELSE BEGIN { tracked out of it } 

result TRUE; 

theltem := 0; { so no item hit } 

END; 

END; 

END; 

keyDown; { keyDown } 

BEGIN 

{Standard return/enter/cmd ' . * processing } 

END; 

otherwise 

BEGIN 
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END; 

END; { case } 
ChooseFilter 


= result; 


END; 


Choose.r 

#define ChooseResourceBase 256 

resource 'DLOG' (ChooseResourceBase, "setup dialog") { 

{0, 0, 70 , 450}, dBoxProc, invisible, noGoAway, 0x0, ChooseResourceBase, 

"Setup Dialog Box" 

}; 

resource *CNTL' (ChooseResourceBase, "Tools control ") { 


{30, 5, 50, 300}, 



popupRightJust, 

/* 

right just */ 

visible. 



90, 

/* 

width of title */ 

ChooseResourceBase, 

/* 

menu associated */ 

popupMenuCDEFproc, 

/* 

no options CDEF 63 = 

0, 

/* 

reference menu 11000, 

"Method:" 

/* 

Title */ 


}; 

resource 'DITL* (ChooseResourceBase, "Basic configuration DITL") { 


{ 


/* array DITLarray: 5 elements */ 

{32, 370, 52, 440), 

Button { 

enabled, "OK" 

}/ 

(5, 370, 25, 440}, 

Button { 

enabled, "Cancel" 

}, 

{28, 366, 56, 444}, 

Userltem { 

enabled 

}, 

{5, 5, 21, 200}, 

StaticText { 

disabled, "Connection Configuration" 

}, 

{30, 5, 50, 300}, /* [5] select tool popup menu user item */ 

Userltem { 

enabled 

} 


/* [ 1 ] */ 

/* [ 2 ] */ 

/* [3] outline of OK button */ 

/* [4] title */ 


} 


}; 

resource 'MENU* (ChooseResourceBase, "Popup Menu") { 

ChooseResourceBase, textMenuProc, allEnabled, enabled, "Choose Menu", 
{ /* Items are added to this menu at execution time */ 


} 


}; 
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Determining whether the managers are installed 

This sample code shows how your application can determine whether the Communications 
Toolbox managers are installed. 

FUNCTION Installed : BOOLEAN; 

CONST 

CommToolboxTrap = $8B; 

UnimplementedTrapNumber = $9F; 


BEGIN 

Installed := TRUE; 

IF NGetTrapAddress(UnimplementedTrapNumber, OSTrap) = 
NGetTrapAddress(CommToolboxTrap, OSTrap) THEN 
BEGIN 

Installed := FALSE; 

END; 

END; 
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Glossary 


background procedure: A procedure that runs 
while the user is using another application. 

cache region: The area in the terminal emulation 
window in which information is displayed that has 
scrolled out of the terminal emulation region. 

channeL A logical line of communication that 
exists on a connection. 

Communications Resource Manager: The 

Communications Toolbox manager that makes it 
easier for your application to register and keep 
track of communications resources. 

communications resource record: A 

Communications Resource Manager data structure 
that contains information such as the type of 
device the record represents, and whether or not 
the device is available for use. 

Communications Toolbox utilities: A 

Communications Toolbox manager that contains 
useful routines, most of which are not specific to 
programming networking or communications 
applications. 

completion routine: Any application-defined 
code to be executed when an asynchronous call to a 
routine is completed. 

connection: A logical line of communication 
between two entities. 

Connection Manager: The Communications 
Toolbox manager that makes it easier for you to 
implement and maintain data connections. 

connection record: A Connection Manager data 
structure containing information that describes 
one instance of a connection tool. 


connection tool: A self-contained collection of 
resources that implements a specific connection 
protocol. 

control definition procedure: A procedure 
called by the Control Manager when it needs to 
implement the functions of a specific type of 
control. 

entity: A task or process running on a computer. 
Two entities can coexist on the same computer if 
the computer is multitasking, like when 
appliations are running in a MultiFinder 
environment. 

File Transfer Manager: The Communications 
Toolbox manager that makes it easier for you to 
implement file transfers. 

file-transfer record: A File Transfer Manager 
data structure that contains all the specifics about 
a file transfer. For example, the file-transfer record 
might show that the File Transfer Manager should 
use the XMODEM tool to perform file transfers, 
and that the tool should not display any custom 
menus while transferring files. 

file-transfer tool: A self-contained collection of 
resources that implements a specific file-transfer 
protocol. 

filter procedure: A routine that Modaioiaiog, 
NuLookup, and NuPLookup Call to filter Or modify 
events that occur in a dialog box. 

Macintosh Toolbox: The software in the 
Macintosh ROM that helps you implement the 
standard Macintosh user interface in your 
application. 
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Name Binding Protocol (NBP); The AppleTalk 
transport-level protocol that translates a character 
string name into the internet address of the 
corresponding socket client. NBP enables 
AppleTalk protocols to understand user-defined 
zones and device names by providing and 
maintaining translation tables that map these 
names to corresponding socket addresses. 

routine: A function or procedure. 

terminal emulation: The process of making a 
computer emulate the characteristics of a terminal. 

terminal emulation buffer: The area in memory 
that contains the data displayed in the terminal 
emulation region. 

terminal emulation region: The area in the 
terminal emulation window in which your 
application writes the output of its terminal 
emulation. This region is the same size (number of 
rows and columns, or pixels) as the screen of the 
terminal your application is emulating. 


te rminal emulation window: The window in 
which your application displays a terminal emulation 
region and cache region. 

terminal environment record: A Terminal 
Manager data structure that reflects the internal 
conditions of a terminal tool. 

Terminal Manner: The Communications Toolbox 
Manager that makes it easier for you to implement 
terminal emulation. 

terminal record: A Terminal Manager data structure 
that contains the specifics of a terminal emulation. 
For example, the terminal record might show that 
your application is emulating a VT320 terminal, and 
that the Terminal Manager should try to cache the 
terminal window before clearing it. 

terminal took A self-contained collection of 
resources that implements the characteristics of a 
specific terminal. 

zone: An arbitrary subset of the networks within 
an internet. 
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idle loops, implementing 
effective 294-296 
Macintosh Communications 
Toolbox managers, 
installing 312 
tool-settings dialog box, 
customizing 302-311 
Communications Folder 5 
Communications Resource 
Manager. See also 
communications resource 
record; specific routines 
data flow of l69 (fig.), 170 
devices 174-175,182-184 
function of 169-170 
head of queue of 176 
ID 180-181 
initalizing 179 
resources 177-179 
routines 

application of 3,169-170 
list of 173 

quick reference to 185-187 
resource mapping 180-181 
selectors 187 
version number 176 
communications resource 
record 170-172 

Communications Toolbox. See 
Macintosh Communications 
Toolbox 

completion routines 34 
_ComTooiTrap trap macro 73 
configuration 
of connection 14 
of connection tool 41-42 
custom 43-46 
of file transfer 15 
of file transfer tool 142-143 
custom 144-147 
of terminal emulation 14-15 
of terminal tool 92-93 
custom 94-97 
configuration record 
in writing own tool 230 


configuration string 
in Connection Manager 47, 63 
in File Transfer Manager 148,153 
localizing 63 

in Terminal Manager 98,108 
connection 
aborting 49 
break procedure 115 
breaks, sending 53 
closing 49 
configuring 14 
initiating 11 
opening 36-42, 48 
resetting 53 

sending data along 114-115 
status information 51 
terminating 11-12 
using 48-55 

connection environment 54-55 
Connection Manager. See also 
connection record; specific 
routines 
channels 29-30 
clean-up operations 45 
closing connection 49 
closing tool file 46 
configuration record 
initializing 40 
sample used in code 40 
validating 40 

configuration string in 47, 63 
connection record for 69 
custom configuration of 
connection tool 43-46 
data flow of 29 (fig.), 30 
data streams 59-60 
and File Transfer Manager 128 
function of 29-30 
handling events 61-62 
initializing 36 
interfacing with scripting 
language 47 

opening connection 36-42, 48 
reading data 56-57 
routines 

application of 3-4, 29 
completion 66 
list of 35 

miscellaneous 64-65 
quick reference to 67-72 
selectors 73 
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and terminal tools 76 
using connection 50-55 
version number 65 
writing data 58 
connection record 
for Connection Manager 69 
creating 38-39 
data structure 31-34 
disposing of 50 
features of 30 
function of 31 
reference constant of 64 
connection requests 50, 52 
connection tool 
completion routines 250 
configuration of 41-42 
and Connection Manager 4 
custom configuration of 43-46 
main code resource for 
function of 235 
messages accepted by 235-250 
quick reference to 251-254 
name of 64 
writing own 

bundle resource for 217-218 
configuration record 230 
function of 217 
initialization request 
message 217 

localization code resource 
229-230 

quick reference to 231-232 
scripting language interface 
code resource 226-228 
setup definition code 
resource 221-225 
validation code resource 
219-221 

constants and data types 
for Communications Resource 
Manager 186-187 
for Connection Manager 70-72 
for File Transfer Manager 164-165 
for Terminal Manager 122-124 
for utilities 212-213 
control definition procedure 
193-197 

Control Manager 190 
conventions, in manual xiii 
countDiTL routine 
description of 201 
sample used in code 306, 307 


CRMGe111ndRe source 

routine 177 

CRMGetlNamedResource 

routine 178 

CRMGetlResource routine 177 
CRMGetCRMVersion routine 176 
CRMGetHeader routine 176 
CRMGetIndex routine 178 
CRMGetIndResource 
routine 177 

CRMGetIndToolName routine 
description of 179 
sample used in code 17,18 
CRMGetNamedResource 

routine 178 

CRMGetResource routine 177 
CRMinstall routine 174 
CRMLocalToRealID routine 
description of 181 
sample used in code 223 
CRMRealToLocallD routine 180 
CRMReleaseResource 

routine 178 

CRMRemove routine 175 
CRMSearch routine 
description of 175 
sample used in code 184 

CRMSerialRecord data 
Structure 182 

'cscr' code resource 218 
' cset ' code resource 218 
CTBGetCTBVersion routine 192 
cursor position 111 
custom tool-settings dialog box 
in Connection Manager 43-45 
in Terminal Manager 94-96 
' cvai ' code resource 217 

D 

DataBuffer record 241 
dataflow 

in Communications Resource 
Manager l69 (fig.), 170 
in Connection Manager 29 (fig.), 
30 

in File Transfer Manager 129 (fig.), 
130 

in Terminal Manager 77 (fig.), 78 
data stream search 
in Connection Manager 59-60 
in Terminal Manager 102-103 


data structures 

communications resource 
record 171-172 
connection record 31-34 
file transfer record 130 
terminal record 80-86 
device management 170 
Device Manager 28, l68 
devices 
installing 174 
registering 182 
removing 175 
searching for 175 
and serial port, searching for 184 
dialog item lists (DITLs) 
appending 198-200 
counting 201 
shortening 201 
Dialog Manager 76,190,2l6 
Digital Equipment Corporation 291 
DITLs. See Dialog item lists 
DoActivate procedure 20 
Dociick procedure 23 
DoCommad procedure 10 
DoConnectionConfig 

procedure 14 

DoFileTransferConfig 
procedure 15 

Doinitiate procedure 11 
DoKey procedure 22-23 
DoKiii procedure 11-12 
DoReceive procedure 13 
DoResume procedure 20-21 
DoSend procedure 12-13 

DoTerminalConfig 

procedure 14-15 
DoUpdate procedure 21-22 

E 

English, translating to and from 
in Connection Manager 63 
in File Transfer Manager 153 
in Terminal Manager 108 
entity 30 

environsProc routine 
description of 118 
in File Transfer Manager 159 
in file transfer record 133 
sample used in code 118,159 
in terminal record 82 
Event Manager 76 
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F 

file 

receiving, starting 13 
sending, starting 12-13 
file transfer 
configuring 15 
preparing 138-143 
processing data 150 
starting 149-150 
stopping 150 

File Transfer Manager. See also File 
transfer record; specific 
routines 

clean-up operations 146 
configuration string in 148,153 
custom configuration of file 
transfer tool 144-147 
data flow in 129 (fig.), 130 
function of 129-130 
handling events 151-152 
initializing 138 
interfacing with scripting 
language 148 

preparing file transfer 138-143 
routines 

application of 3,129-130 
list of 137 

miscellaneous 154-155 
provided by application 
156-160 

quick reference to l6l-l65 
selectors 165-166 
transferring files 149-150 
version number 155 
file transfer record 
creating 139-140 
data structure of 131-136 
disposing 150 
features of 130 
function of 130 
initializing 141 
validating 141 
file transfer tool 
configuring 142-143 
custom configuration of 144-147 
function of 129 
main code resource for 
function of 279 
messages accepted by 279-282 
quick reference to 283-284 
name of 154 


writing own 

bundle resource for 217-218 
configuration record 230 
function of 217 
initialization request 
message 217 

localization code resource 
229-230 

quick reference to 231-232 
scripting language interface 
code resource 226-228 
setup definition code 
resource 221-225 
validation code resource 
219-221 
filter procedure 

in configuring connection tool 42 
definition of 206 
name 206 
zone 207 

FindSerialPorts 

procedure 184 
FTAbort routine 150 
ftAbortMsg message 281 
FTActivate routine 
description of 151 
sample used in code 20 
ftActivateMsg message 281-282 
FTChoose routine 
description of 142-143 
sample used in code 15 
ftDeactivateMsg message 282 
FTDefauit routine 141 
FTDispose routine 
description of 150 
sample used in code 19 
ftDisposeMsg message 280 
FTEnglishToIntl routine 153 
FTEvent routine 152 
ftEventMsg message 282 
FTExec routine 
description of 150 
sample used in code 295 
using 294 

ftExecMsg message 281 
FTGetconfig routine 148 
FTGetFTVersion routine 155 
FTGetProciD routine 
description of 139 
sample used in code 18 
FTGetRefCon routine 154 
FTGetToolName routine 154 


FTGetUserData routine 155 
FTGetVersion routine 155 
ftinitMsg message 217,279-280 
FTIntlToEnglish routine 153 
FTMenu routine 
description of 152 
sample used in code 10 
ftMenuMsg message 282 
FTNew routine 
description of 139-140 
sample used in code 18 
ftPrivate 133 
FTResume routine 
description of 151 
sample used in code 21 
ftResumeMsg message 281-282 
FTSetconfig routine 148 
FTSetRefCon routine 154 
FTSetupCleanup routine 146 
FTSetupFilter routine 145 
FTSetupitem routine 146 
FTSetupPostflight 

routine 147 

FTSetupPreflight routine 144 
FTSetupSetup routine 145 
FTSetUserData routine 155 
FTStart routine 
description of 149 
sample used in code 13,18 
ftstartMsg message 280-281 
ftSuspendMsg message 282 
FTValidate routine 
description of I4l 
sample used in code I4l 

G 

globals 9 

H 

hard disk 5 
hardware 5 

hook procedure 206-210 
HyperCard 5 

ID 

mapping to Local ID 180 
mapping to Real ID 181 
initCM routine 36 
initCRM routine 174 
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InitCTBUtilitles routine 192 
initFT routine 138 
initTM routine 88 
installation of tools 5 
installation of communications 
Toolbox managers sample 
code 312 

installing devices 174 
interfacing 
between Macintosh 

Communications Toolbox 
applications and tools 4, 

5 (fig.) 

scripting language code 
resource 226-228 
user interface considerations 
287-291 

with scripting language 47,98,148 
IsConnEvent function 298-299 
isFTEvent function 297-298 
isFTWindow function 297-298 
IsTermEvent function 299-300 

K 

Keyboard events 
procedures for 22-23 
in Terminal Manager 106 

L 

localization code resource 229-230 

M 

Macintosh Communications 
Toolbox. See also specific 
managers 
contents of 3-4 
function of 8 
globals used in 9 
installation of 5 

interface between application and 
tools 4,5 (fig.) 
managers in 3-4 
reference manual for xi-xiii 
requirements for 5 
sample application of 8-25 
sections of 9 

Macintosh computers 5, 291 
Macintosh Operating System trap 73 
Main program loop in sample 
code 24-25, 300-301 


MakeNew procedure in sample 
code 16-18 
Memory Manager l68 
menu choices, handling 10 
Menu events 

closing session document 19 
configuring connection 14 
configuring file transfer 15 
configuring terminal 
emulation 14-15 
in Connection Manager 6l 
in File Transfer Manager 152 
handling menu choices 10 
initiating connection 11 
making new session 
document 16-18 
receiving file 13 
sending file 12-13 
in Terminal Manager 105 
terminating connection 11-13 
modeless tools 288 
Mouse events 
clikLoop 118 
procedure for 23 
in Terminal Manager 106 
MultiFinder 5, 168 
MyCompietion routine 66 
MyHookProc routine 208-209 
MyNameFilter routine 206 
MySearchCallBack routine 60 
MyZoneFilter routine 207 

N 

name filters 206 

network look-up utilities 202 (fig.), 
203-205 

NewControi routine 193 
NuLookup routine 202-204 
NuPLookup routine 202, 204-205 

0 

Operating System Utilities l68 

P 

pop-up menu control definition 
procedure 193-197 
PopUpMenuSelect function 193 
popupUseAddResMenu variation 
code constant 195 


popupUseCQD variation code 
constant 195 

popupUsewfont variation code 
constant 195 
programming problems 
custom tool-settings dialog 
box 302-311 

events needed to be handled by 
Macintosh Communications 
Toolbox managers 297-301 
idle loops 294-296 
installation of Macintosh 

Communications Toolbox 
managers 312 

Q 

QuickDraw 76 

R 

removing devices 175 
Resource management 170 
Resource Manager 
and Communications Resource 
Manager l68 

and Connection Manager 28 
and File Transfer Manager 128 
and Terminal Manager 76 
and utilities 190 

resource-mapping routines 180 
resources 

getting usage index for 178 
loading 177-178 
loading indexed 177 
loading named 178 
releasing 178 
Resume events 
in Connection Manager 6l 
in File Transfer Manager 151 
procedure for 20-21 
in Terminal Manager 105 
routines. See also specific names of 
Communications Resource 
Manager 

application of 3,169-170 
description of 177-179 
list of 173 

quick reference to 185-187 
resource mapping 180-181 
selectors 187 
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u 

update events 
procedures for 21-22 
in Terminal Manager 106 
Update procedure 
sample used in code 22 
utilities 

and AppleTalk 202-205 
DITLs 198-201 
initializing 192 

pop-up menu control definition 
procedure 193-197 


routines 
list of 191 

quick reference to 211-214 
selectors 214 
version number 192 


V 

validation code resource 219-221 
variation codes 194 
version number 
Communications Resource 
Manager 176 



Connection Manager 65 
File Transfer Manager 155 
Terminal Manager 110 
utilities 192 
viewRect 84 
visRect 84 
VT102 terminal setting 291 

W, X, Y, Z 

writeProc routine 159 
XMODEM tool 129 
zone filters 207 
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